Designing and Implementing a Template

The design of a Template reflects the query-building elements of the user interface of an application. For example, suppose you want to develop an application that allows the end user to create a query that requests a number of values from the top or bottom of a list of values. The values are from one dimension of a measure. The other dimensions of the measure are limited to single values.

The user interface of your application has a dialog box that allows the end user to do the following:

• Select a radio button that specifies whether the data values should be from the top or bottom of the range of values.
• Select a measure from a drop-down list of measures.
• Select a number from a field. The number specifies the number of data values to display.
• Select one of the dimensions of the measure as the base of the data values to display. For example, if the user selects the product dimension, then the query specifies some number of products from the top or bottom of the list of products. The list is determined by the measure and the selected values of the other dimensions.
• Click a button to bring up a Single Selections dialog box through which the end user selects the single values for the other dimensions of the selected measure. After selecting the values of the dimensions, the end user clicks an OK button on the second dialog box and returns to the first dialog box.
• Click an OK button to generate the query. The results of the query appear.

To generate a Source that represents the query that the end user creates in the first dialog box, you design a Template called TopBottomTemplate. You also design a second Template, called SingleSelectionTemplate, to create a Source that represents the end user's selections of single values for the dimensions other than the base dimension. The designs of your Template objects reflect the user interface elements of the dialog boxes.

In designing the TopBottomTemplate and its MetadataState and SourceGenerator, you do the following:

• Create a class called TopBottomTemplate that extends Template. To the class, you add methods that get the current state of the Template, set the values specified by the user, and then set the current state of the Template.
• Create a class called TopBottomTemplateState that implements MetadataState. You provide fields on the class to store values for the SourceGenerator to use in generating the Source produced by the Template. The values are set by methods of the TopBottomTemplate.
• Create a class called TopBottomTemplateGenerator that implements SourceGenerator. In the generateSource method of the class, you provide the operations that create the Source specified by the end user's selections.

Using your application, an end user selects sales amount as the measure and products as the base dimension in the first dialog box. From the Single Selections dialog box, the end user selects customers from San Francisco, the first quarter of 2000, the direct channel, and billboard promotions as the single values for each of the remaining dimensions.

The query that the end user has created requests the ten products that have the highest total sales amount values of those sold through the direct sales channel to customers from San Francisco during the first calendar quarter of the year 2000 while a billboard promotion was occurring.

For examples of implementations of the TopBottomTemplate, TopBottomTemplateState, and TopBottomTemplateGenerator objects, and an example of an application that uses them, see Example 10-1, Example 10-2, Example 10-3, and Example 10-4.

Implementing the Classes for a Template

Example 10-1 is an implementation of the TopBottomTemplate class.

Example 10-1 Implementing a Template

package myTestPackage;

import oracle.olapi.data.source.DataProvider;
import oracle.olapi.data.source.DynamicDefinition;
import oracle.olapi.data.source.Source;
import oracle.olapi.data.source.Template;
import oracle.olapi.transaction.metadataStateManager.MetadataState;

/**
 * Creates a TopBottomTemplateState, a TopBottomTemplateGenerator,
 * and a DynamicDefinition. Gets the current state of the 
 * TopBottomTemplateState and the values it stores. Sets the data values
 * stored by the TopBottomTemplateState and sets the changed state as
 * the current state.
 */
public class TopBottomTemplate extends Template {
  public static final int TOP_BOTTOM_TYPE_TOP = 0;
  public static final int TOP_BOTTOM_TYPE_BOTTOM = 1;

  // Variable to store the DynamicDefinition.
  private DynamicDefinition _definition;

  /**
   * Creates a TopBottomTemplate with default type and number values
   * and a specified base dimension.
   */
  public TopBottomTemplate(Source base, DataProvider dataProvider) {
    super(new TopBottomTemplateState(base, TOP_BOTTOM_TYPE_TOP, 0),
                                     dataProvider);
    // Create the DynamicDefinition for this Template. Create the 
    // TopBottomTemplateGenerator that the DynamicDefinition uses.
    _definition = 
    createDynamicDefinition(new TopBottomTemplateGenerator(dataProvider));
  }

  /**
   * Gets the Source produced by the TopBottomTemplateGenerator
   * from the DynamicDefinition.
   */
  public final Source getSource() {
    return _definition.getSource();
  }

  /**
   * Gets the Source that is the base of the values in the result set.
   * Returns null if the state has no base.
   */
  public Source getBase() {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    return state.base;
  }

  /**
   * Sets a Source as the base.
   */
  public void setBase(Source base) {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    state.base = base;
    setCurrentState(state);
  }

  /**
   * Gets the Source that specifies the measure and the single
   * selections from the dimensions other than the base.
   */
  public Source getCriterion() {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    return state.criterion;
  }

  /**
   * Specifies a Source that defines the measure and the single values 
   * selected from the dimensions other than the base.
   * The SingleSelectionTemplate produces such a Source.
   */
  public void setCriterion(Source criterion) {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    state.criterion = criterion;
    setCurrentState(state);
  }

  /**
   * Gets the type, which is either TOP_BOTTOM_TYPE_TOP or 
   * TOP_BOTTOM_TYPE_BOTTOM.
   */
  public int getTopBottomType() {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    return state.topBottomType;
  }

  /**
   * Sets the type.
   */
  public void setTopBottomType(int topBottomType) {
    if ((topBottomType < TOP_BOTTOM_TYPE_TOP) ||
        (topBottomType > TOP_BOTTOM_TYPE_BOTTOM    ))
      throw new IllegalArgumentException("InvalidTopBottomType");
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    state.topBottomType = topBottomType;
    setCurrentState(state);
  }

  /**
   * Gets the number of values selected.
   */
  public float getN() {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    return state.N;
  }

  /**
   * Sets the number of values to select.
   */
  public void setN(float N) {
    TopBottomTemplateState state = (TopBottomTemplateState) getCurrentState();
    state.N = N;
    setCurrentState(state);
  }
}

Example 10-2 is an implementation of the TopBottomTemplateState class described earlier.

Example 10-2 Implementing a MetadataState

package myTestPackage;

import oracle.olapi.data.source.Source;
import oracle.olapi.transaction.metadataStateManager.MetadataState;

/**
 * Stores data that can be changed by its TopBottomTemplate.
 * The data is used by a TopBottomTemplateGenerator in producing
 * a Source for the TopBottomTemplate.
 */
public final class TopBottomTemplateState
     implements Cloneable, MetadataState {
  public int topBottomType;
  public float N;
  public Source criterion;
  public Source base;

  /**
   * Creates a TopBottomTemplateState.
   */
  public TopBottomTemplateState(Source base, int topBottomType, float N) {
    this.base = base;
    this.topBottomType = topBottomType;
    this.N = N;
  }

  /**
   * Creates a copy of this TopBottomTemplateState.
   */
  public final Object clone() {
    try {
      return super.clone();
    }
    catch(CloneNotSupportedException e) {
      return null;
    }
  }
}

Example 10-3 is an implementation of the TopBottomTemplateGenerator class described earlier.

Example 10-3 Implementing a SourceGenerator

package myTestPackage;

import oracle.olapi.data.source.DataProvider;
import oracle.olapi.data.source.Source;
import oracle.olapi.data.source.SourceGenerator;
import java.lang.Math;

/**
 * Produces a Source for a TopBottomTemplate based on the data
 * values of a TopBottomTemplateState.
 */
public final class TopBottomTemplateGenerator
      implements SourceGenerator {
  // Store the DataProvider.
  private DataProvider _dataProvider;

  /**
   * Creates a TopBottomTemplateGenerator.
   */
  public TopBottomTemplateGenerator(DataProvider dataProvider) {
    _dataProvider = dataProvider;
  }

  /**
   * Generates a Source for a TopBottomTemplate using the current 
   * state of the data values stored by the TopBottomTemplateState.
   */
  public Source generateSource(MetadataState state) {
    TopBottomTemplateState castState = (TopBottomTemplateState)state;
    if (castState.criterion == null)
      throw new NullPointerException("CriterionParameterMissing");
    Source sortedBase = null;
    if (castState.topBottomType == TOP_BOTTOM_TYPE_TOP)
      sortedBase = castState.base.sortDescending(castState.criterion);
    else
      sortedBase = castState.base.sortAscending(castState.criterion);
    return sortedBase.interval(1, Math.round(castState.N));
  }
}

Implementing an Application That Uses Templates

After you have stored the selections made by the end user in the MetadataState for the Template, use the getSource method on the DynamicDefinition to get the Source created by the Template. This section provides an example of an application that uses the TopBottomTemplate described in Example 10-1. For brevity, the code does not contain much exception handling.

The Context class used in the example has methods that do the following:

• Connects to Oracle OLAP.
• Opens a database.
• Gets metadata objects for the measure and the dimensions selected by the end user.
• Gets primary Source objects from the metadata objects.

The example does the following:

• Gets primary Source objects from the Context.
• Creates a SingleSelectionTemplate for selecting single values from some of the dimensions of the measure.
• Creates a TopBottomTemplate and stores selections made by the end user.
• Gets the Source produced by the TopBottomTemplate.
• Creates a Cursor for that Source.
• Gets the values from the Cursor and displays them.

Example 10-4 does not include the code for interacting with the end user or for implementing the SingleSelectionTemplate or the MetadataState and SourceGenerator objects for the SingleSelectionTemplate. The example class has a method for creating a Cursor and a method for printing the values of the Cursor. All other operations occur in the main method. The Context object supplies the connection to the database, the DataProvider and the TransactionProvider, and primary Source objects.

Example 10-4 Getting the Source Produced by the Template

package myTestPackage;

import oracle.olapi.data.source.Source;
import oracle.olapi.data.source.StringSource;
import oracle.olapi.data.source.DataProvider;
import oracle.olapi.data.source.CursorManagerSpecification;
import oracle.olapi.data.cursor.CursorManager;
import oracle.olapi.data.source.SpecifiedCursorManager;
import oracle.olapi.data.cursor.Cursor;
import oracle.olapi.data.cursor.ValueCursor;
import oracle.olapi.transaction.NotCommittableException;
import myTestPackage.Context;
import myTestPackage.TopBottomTemplate;
import myTestPackage.SingleSelectionTemplate;

/**
 * Creates a query that specifies a number of values from the top or
 * bottom of a list of values from one of the dimensions of a measure.
 * The list is determined by the measure and by single values from
 * the other dimensions of the measure. Displays the results of the
 * query.
 */
public class TopBottomTest {
  /**
   * Prints the values of the Cursor.
   */
  public static void printCursor(Cursor cursor) {

    // Because the result is a single set of values with no outputs,
    // cast the Cursor to a ValueCursor and print out the values.
    ValueCursor valueCursor = (ValueCursor) cursor;
    int i = 1;
    do {
      System.out.println(i + ". " + valueCursor.getCurrentValue());
      i++;
    } while(valueCursor.next());
  }

  /**
   * Creates a Cursor.
   */
  public static void createCursor(Source choice, DataProvider dp) {
    CursorManagerSpecification cursorMngrSpec = 
                       dp.createCursorManagerSpecification(choice);
    SpecifiedCursorManager cursorManager =
                       dp.createCursorManager(cursorMngrSpec);
    Cursor cursor = cursorManager.createCursor();
    // Print the values of the Cursor.
    printCursor(cursor);
    // Close the CursorManager.
    cursorManager.close();
  }

  public static void main(String[] args) {

    // Create a Context object and from it get the DataProvider and
    // the primary Source objects for the measure and the dimensions.
    Context context = new Context();
    DataProvider dp = context.getDataProvider();
    Source[] sources = context.getPrimarySourcesByName(
          new String[]{"SALES_AMOUNT", "PRODUCTS_DIM", "CUSTOMERS_DIM",
                       "CHANNELS_DIM", "TIMES_DIM", "PROMOTIONS_DIM"});
    Source salesAmount = sources[0];
    StringSource product = (StringSource)sources[1];
    StringSource customer = (StringSource)sources[2];
    StringSource channel = (StringSource)sources[3];
    StringSource time = (StringSource)sources[4];
    StringSource promo = (StringSource)sources[5];

    // Create a SingleSelectionTemplate to produce a Source that
    // specifies a single value for each of the dimensions other
    // than the base for the selected measure.
    SingleSelectionTemplate singleSelections = 
                        new SingleSelectionTemplate(salesAmount, dp);
    singleSelections.addSelection((StringSource) customer, 
                                                "San Francisco");
    singleSelections.addSelection((StringSource) time, "2000-Q1");
    // S is the direct sales channel
    singleSelections.addSelection((StringSource) channel, "S");
    singleSelections.addSelection((StringSource) promo, "billboard");

    // Create a TopBottomTemplate and set the parameters selected by
    // the end user, including a dimension as the base and the
    // Source produced by the SingleSelectionTemplate as the
    // criterion.
    TopBottomTemplate topNBottom = new TopBottomTemplate(product, dp);
    topNBottom.setTopBottomType(TopBottomTemplate.TOP_BOTTOM_TYPE_TOP);
    topNBottom.setN(15);
    topNBottom.setCriterion(singleSelections.getSource());

    // With methods on the TransactionProvider, prepare and commit
    // the transaction.
    try{
      context.getTransactionProvider().prepareCurrentTransaction();
    }
    catch(NotCommittableException e){
      System.out.println("Cannot prepare current Transaction. " +
                         "Caught exception " + e + ".");
    }
    context.getTransactionProvider().commitCurrentTransaction();

    // Get the Source produced by the TopBottomTemplate,
    // create a Cursor for it and display the results.
    createCursor(topNBottom.getSource(), dp);
  }
}