Example 5-2 A Simple Join That Produces a Source with an Output

This example uses the simplest signature of the join method to produce a Source that has one output. The example creates a list Source, letters, that has three elements, the values of which are A, B, and C. It also creates a list Source, names, that has three elements, the values of which are Stephen, Leo, and Molly.

Source letters = dp.createListSource(new String[] {"A", "B", "C"});
Source names = dp.createListSource(new String[] {"Stephen", "Leo", "Molly"});
Source lettersWithNames = letters.join(names);

// Oracle OLAP translates this shortcut signature of the join method into the
// following full signature, where dp is the DataProvider for the session.
// Source letters.join(names,
//                     dp.getEmptySource(),
//                     Source.COMPARISON_RULE_REMOVE,
//                     true);

The letters.join(names) operation joins the elements of the base Source, letters, and the joined Source, names. Because the comparison Source has no elements, the join operation does not remove any of the elements that are in the joined Source in producing the derived Source. (The comparison Source is the empty Source that is returned by the dp.getEmptySource() parameter of the full join signature shown in the example.) The resulting derived Source, lettersWithNames, is the Cartesian product of the elements of the base letters and the joined names. Because both letters and names have three elements, the number of elements in lettersWithNames is nine.

Because the visible parameter of letters.join(names) is true, the derived Source has an output. Because no elements were removed from the joined Source, the derived Source has the values of all of the elements of the joined Source.

A Cursor for a Source has the same structure as the Source. A Cursor for the lettersWithNames Source has a ValueCursor for the base values of the derived Source and a ValueCursor for the output values. The following table presents the values of the ValueCursor objects. The table includes headings that are not in the ValueCursor objects.

Output Values     Base Values
   Stephen             A
   Stephen             B
   Stephen             C
   Leo                 A
   Leo                 B
   Leo                 C
   Molly               A
   Molly               B
   Molly               C

Example 5-3 A Simple Join That Selects Elements of the Joined Source

This example demonstrates using a comparison Source that has values and the comparison rule COMPARISON_RULE_SELECT. The example uses the letter and names Source objects from Example 5-2 and adds the someNames Source. It uses someNames as the comparison Source. The output of the Source derived from the join operation has only the names that are in both the joined Source and the comparison Source.

Source someNames = dp.createListSource(new String[] {"Stephen", "Molly"});
Source lettersAndSelectedNames = 
  letters.join(names, someNames, Source.COMPARISON_RULE_SELECT, true);

A Cursor for the lettersAndSelectedNames Source has the values specified by the Source. The following table presents the Cursor values and has headings added.

Output Values     Base Values
   Stephen             A
   Stephen             B
   Stephen             C
   Molly               A
   Molly               B
   Molly               C

Example 5-4 A Simple Join That Removes Elements of the Joined Source

This example demonstrates using a comparison Source that has values and the comparison rule COMPARISON_RULE_REMOVE. That comparison rule removes from participation in the join operation those values that are the same in the joined and in the comparison Source objects. The output of the derived Source therefore has only the name from the joined Source that is not in the comparison Source.

The example has the same base, joined, and comparison Source objects as Example 5-3.

Source lettersAndNamesWithoutRemovedNames =
  letters.join(names,
               someNames,
               Source.COMPARISON_RULE_REMOVE, 
               true);

A Cursor for the lettersAndNamesWithoutRemovedNames Source has the values specified by the Source. The following table presents the values and has headings added.

Output Values     Base Values
   Leo                 A
   Leo                 B
   Leo                 C

Example 5-5 A Simple Join That Produces a Source with Two Outputs

If you join a Source to a Source that has an output, and if the visible parameter is true, then the join operation produces a Source that has the joined Source as an additional output. The additional output becomes the first output, as shown in this example.

The example uses the Source objects from Example 5-3 and creates another list Source, colors, that contains the names of two colors. The example joins the colors Source to the lettersWithSelectedNames Source to produce the lettersWithSelectedNamesAndColors Source.

The lettersWithSelectedNames Source has names as an output. The lettersWithSelectedNamesAndColors Source has both colors and names as outputs. The first output is colors and the second output is names.

Source colors = dp.createListSource(new String[] {"Green", "Maroon"});

Source lettersWithSelectedNames = 
  letters.join(names,
               someNames,
               Source.COMPARISON_RULE_SELECT,
               true);
Source lettersWithSelectedNamesAndColors =
  lettersWithSelectedNames.join(colors);

A Cursor for the lettersWithSelectedNamesAndColors Source has the values shown in the following table. The table has headings added.

Output 1 Values     Output 2 Values     Base Values
      Green            Stephen               A
      Green            Stephen               B
      Green            Stephen               C
      Green            Molly                 A
      Green            Molly                 B
      Green            Molly                 C
      Maroon           Stephen               A
      Maroon           Stephen               B
      Maroon           Stephen               C
      Maroon           Molly                 A
      Maroon           Molly                 B
      Maroon           Molly                 C

Example 5-6 A Simple Join That Hides An Output

If the visible parameter of a join method is false, then the joined Source participates in the join operation but does not appear as an output of the Source derived by the join. This example uses the joinHidden shortcut method to join the lettersWithSelectedNames and the colors Source objects from Example 5-5. The example includes in a comment the full join signature for the joinHidden shortcut.

Source lettersWithSelectedNamesAndHiddenColors =
  lettersWithSelectedNames.joinHidden(colors);

// The full signature of the joinHidden shortcut method is
// Source result = base.join(joined,
//                           dp.getEmptySource(),
//                           Source.COMPARISON_RULE_REMOVE,
//                           false);
// So if Source base = lettersWithSelectedNames and
// Source joined = colors, then the result Source is the same as the 
// lettersWithSelectedNamesAndHiddenColors Source.

A Cursor for the lettersWithSelectedNamesAndHiddenColors Source has the values shown in the following table. The table has headings added.

Note that the derived lettersWithSelectedNamesAndHiddenColors Source still has twelve elements, even though the values for the colors Source do not appear as output values. The derived Source has one set of the six values of the lettersWithSelectedNames Source for each value of the hidden colors Source.

The example displays the following output.

Output Values     Base Values
   Stephen             A
   Stephen             B
   Stephen             C
   Molly               A
   Molly               B
   Molly               C
   Stephen             A
   Stephen             B
   Stephen             C
   Molly               A
   Molly               B
   Molly               C

Example 5-7 Getting an Attribute for a Dimension Member

MdmStandardDimension mdmChanDim =
  mdmDBSchema.findOrCreateStandardDimension("CHANNEL_AWJ");
Source chanDim = mdmChanDim.getSource();
Source locValAttr = mdmChanDim.getLocalValueAttribute().getSource();
Source dimMembersWithLocalValue = locValAttr.join(chanDim);

Example 5-8 Getting Measure Values

This example demonstrates matching the inputs of the base Source with the joined Source. In the example, mdmDBSchema is the MdmDatabaseSchema for the GLOBAL schema.

MdmCube mdmPriceCube =
  mdmDBSchema.findOrCreateCube("PRICE_CUBE_AWJ");
MdmBaseMeasure mdmUnitPrice =
  mdmPriceCube.findOrCreateBaseMeasure("UNIT_PRICE");
MdmStandardDimension mdmProdDim =
  mdmDBSchema.findOrCreateStandardDimension("PRODUCT_AWJ");
MdmTimeDimension mdmTimeDim =
  mdmDBSchema.findOrCreateTimeDimension("TIME_AWJ");

Source prodDim = mdmProdDim.getSource();
Source timeDim = mdmTimeDim.getSource();
Source unitPrice = mdmUnitPrice.getSource();

Source pricesByProductAndTime = unitPrice.join(prodDim).join(timeDim);
NumberSource numPricesByProductAndTime = pricesByProductAndTime.count();

Example 5-9 Using the value Method to Relate a Source to Itself

In this example, the lettersValue Source is returned by the letters.value() method. The lettersValue Source has letters as an input. The input represents a relation between the values of the Source with the input and the values of the Source that matches with the input.

The join operation has letters as the base Source and lettersValue as the joined Source. The base Source, letters, matches with the input of lettersValue, which is also letters, because they are the same. The Source produced by the join operation, lettersByLettersValue has lettersValue as an output. It does not have an input. Each element of lettersByLettersValue has a base value from letters and the related value from lettersValue.

Source letters = dp.createListSource(new String[] {"A", "B", "C"});
Source lettersValue = letters.value();
Source lettersByLettersValue = letters.join(lettersValue); 

A Cursor for the lettersByLettersValue Source has the values shown in the following table. The table has headings added.

Output Values     Base Values
       A               A
       B               B
       C               C

Because lettersByLettersValue contains only those values of the base and joined Source objects that are related, the base values of the Cursor for lettersByLettersValue Source are the same as the output values. If the base and joined Source objects had been unrelated, as in letters.join(letters), then the Source produced by the join operation would contain the Cartesian product of the base and joined Source objects.

Example 5-10 Using the value Method to Select Elements of a Source

By using the value method, you can derive a Source that is a selection of the elements of another Source. This example selects two elements from the Source for the PRODUCT_AWJ dimension from Example 5-7. This example demonstrates a base Source matching with the input of the joined Source.

Source productsToSelect = dp.createListSource(new String[]
                                  {"PRODUCT_PRIMARY::ITEM::ENVY EXE",
                                   "PRODUCT_PRIMARY::ITEM::ENVY STD"});
Source selectedProducts = prodDim.join(prodDim.value(),
                                       productsToSelect,
                                       Source.COMPARISON_RULE_SELECT,
                                       false);  // Hide the output.

A Cursor for the productsToSelect Source has the following values.

PRODUCT_PRIMARY::ITEM::ENVY EXE
PRODUCT_PRIMARY::ITEM::ENVY STD

A Cursor for the selectedProducts Source has the following values.

PRODUCT_PRIMARY::ITEM::ENVY EXE
PRODUCT_PRIMARY::ITEM::ENVY STD

The two Source objects contain the same values. However, the types of the objects are different. The type of the productsToSelect Source is the Source for the FundamentalMetadataObject for the String data type. The type of the selectedProducts Source is prodDim because selectedProducts is derived from prodDim. Therefore, selectedProducts is a subtype of prodDim and as such it can match with a Source that has the Source for the PRODUCT_AWJ dimension as an input, as shown in the next example.

Example 5-11 Using Derived Source Objects to Select Measure Values

This example selects elements from the Source objects for two dimensions and then gets the measure values for the selected dimension members. The example uses the same dimensions and measure as in Example 5-8. In this example, however, the Source objects that match with the inputs of the Source for the measure are not the Source objects for the dimensions. Instead they are subtypes of the Source objects for the dimensions. The subtypes specify selected members of the dimensions. The Source that is derived by joining the measure with the dimensions, pricesForSelectedProductsAndTimes, has six elements, which specify only the measure values for the two products for the three time values, instead of the 4998 elements of the pricesByProductAndTime Source in Example 5-8. In this example, mdmDBSchema is the MdmDatabaseSchema for the GLOBAL schema.

// Create lists of product and time dimension members.
Source productsToSelect = dp.createListSource(new String[]
                                           {"PRODUCT_PRIMARY::ITEM::ENVY EXE",
                                            "PRODUCT_PRIMARY::ITEM::ENVY STD"});
Source timesToSelect = dp.createListSource(new String[]
                                           {"CALENDAR_YEAR::MONTH::2000.01",
                                            "CALENDAR_YEAR::MONTH::2001.01",
                                            "CALENDAR_YEAR::MONTH::2002.01"});
// Get the PRICE_CUBE_AWJ cube.
MdmCube mdmPriceCube = mdmDBSchema.findOrCreateCube("PRICE_CUBE_AWJ");
// Get the UNIT_PRICE measure from the cube.
MdmBaseMeasure mdmUnitPrice = 
  mdmPriceCube.findOrCreateBaseMeasure("UNIT_PRICE");
// Get the PRODUCT_AWJ and TIME_AWJ dimensions.
MdmStandardDimension mdmProdDim =
  mdmDBSchema.findOrCreateStandardDimension("PRODUCT_AWJ");
MdmTimeDimension mdmTimeDim =
  mdmDBSchema.findOrCreateTimeDimension("TIME_AWJ");
// Get the Source objects for the dimensions and the measure.
Source prodDim = mdmProdDim.getSource();
Source timeDim = mdmTimeDim.getSource();
Source unitPrice = mdmUnitPrice.getSource();
// Using the value method, derive Source objects that specify the selected 
// dimension members.
Source selectedProducts = prodDim.join(prodDim.value(),
                                       productsToSelect,
                                       Source.COMPARISON_RULE_SELECT,
                                       false);
Source selectedTimes = timeDim.join(timeDim.value(),
                                    timesToSelect,
                                    Source.COMPARISON_RULE_SELECT,
                                    false);
// Derive a Source that specifies the unitPrice values for the selected products
// and times.
Source pricesForSelectedProductsAndTimes = unitPrice.join(selectedProducts)
                                                    .join(selectedTimes);

A Cursor for the pricesForSelectedProductsAndTimes Source has the values shown in the following table. The table has headings added.

            Month                         Product                Price
-----------------------------  -------------------------------  -------
CALENDAR_YEAR::MONTH::2000.01  PRODUCT_PRIMARY::ITEM::ENVY EXE  3358.02
CALENDAR_YEAR::MONTH::2000.01  PRODUCT_PRIMARY::ITEM::ENVY STD  3000.11
CALENDAR_YEAR::MONTH::2001.01  PRODUCT_PRIMARY::ITEM::ENVY EXE  3223.28
CALENDAR_YEAR::MONTH::2001.01  PRODUCT_PRIMARY::ITEM::ENVY STD  2426.07
CALENDAR_YEAR::MONTH::2002.01  PRODUCT_PRIMARY::ITEM::ENVY EXE  3008.95
CALENDAR_YEAR::MONTH::2002.01  PRODUCT_PRIMARY::ITEM::ENVY STD  2140.71

Example 5-12 Extracting Elements of a Source

This example uses the selectValues method to derive two selections of elements from a StringSource for the PRODUCT_AWJ dimension. The selectValues method is a shortcut for the full join signature of the methods in Example 5-10 and Example 5-11 that produce the selectedProducts and selectedTimes Source objects.

This example creates a list Source, sourcesToCombine, that has the two derived Source objects as element values. The sourcesToCombine.extract() method produces sourcesToCombineWithAnInput, which is a Source that has sourcesToCombine as an input. The join operation sourcesToCombineWithAnInput.joinHidden(sourcesToCombine) matches the input of sourcesToCombineWithAnInput with the joined sourcesToCombine and produces combinedSources, which has no inputs or outputs. A shortcut for this combining of Source elements is the appendValues method.

MdmStandardDimension mdmProdDim =
  mdmDBSchema.findOrCreateStandardDimension("PRODUCT_AWJ");
StringSource prodDim = (StringSource) mdmProdDim.getSource();
Source productsToSelect = prodDim.selectValues(new String[]
                                           {"PRODUCT_PRIMARY::ITEM::ENVY ABM",
                                            "PRODUCT_PRIMARY::ITEM::ENVY EXE",
                                            "PRODUCT_PRIMARY::ITEM::ENVY STD"});
Source moreProductsToSelect = prodDim.selectValues(new String[]
                                           {"PRODUCT_PRIMARY::ITEM::SENT FIN",
                                            "PRODUCT_PRIMARY::ITEM::SENT MM",
                                            "PRODUCT_PRIMARY::ITEM::SENT STD"});
Source sourcesToCombine = 
  dp.createListSource(new Source[] {productsToSelect, moreProductsToSelect});
Source sourcesToCombineWithAnInput = sourcesToCombine.extract();
Source combinedProducts = 
  sourcesToCombineWithAnInput.joinHidden(sourcesToCombine);

A Cursor for the combinedProducts Source has the following values.

PRODUCT_PRIMARY::ITEM::ENVY ABM
PRODUCT_PRIMARY::ITEM::ENVY EXE
PRODUCT_PRIMARY::ITEM::ENVY STD
PRODUCT_PRIMARY::ITEM::SENT FIN
PRODUCT_PRIMARY::ITEM::SENT MM
PRODUCT_PRIMARY::ITEM::SENT STD