oracle.olapi.data.source
Class Template

java.lang.Object
  |
  +--oracle.olapi.data.source.Template

public abstract class Template

extends java.lang.Object

The basis for creating a Source that an application can dynamically change. An application can use a Template to turn the selections made by an end user into Source objects.

A Template has the following component objects:

• A Template
• A MetadataState
• A DataProvider
• A SourceGenerator
• A DynamicDefinition

The components work together as follows:

• The Template has methods that create a DynamicDefinition and that get and set the current state of a MetadataState. An extension to the Template abstract class adds methods to get values from its MetadataState and to put values into the fields on the MetadataState.
• The MetadataState implementation has fields for storing the data to use in generating the Source for the Template. An application passes the MetadataState to the constructor when creating a new Template. When the application calls the getSource on the DynamicDefinition, the MetadataState is passed to the generateSource method on the SourceGenerator.
• The DataProvider is used by the Template in creating a DynamicDefinition.
• The SourceGenerator implementation has a generateSource method that uses the current state of the data in the MetadataState to produce the Source that the Template defines. The application passes the SourceGenerator to the createDynamicDefinition method on the Template to create a DynamicDefinition.
• The DynamicDefinition has a getSource method that gets the Source generated by the SourceGenerator. The DynamicDefinition serves as a proxy for the immutably paired SourceDefinition of that Source.

The application can use the Source produced by the Template in creating a Cursor to fetch the data defined by the Source. It can also use the Source in creating another Source.

The application can use Source objects produced by different Template objects in the process of creating a Source that represents a complex query. The application can change the selection of data for any one of the Template objects that comprise the complex query. Since the DynamicDefinition that gets the Source for a Template is a proxy, the application does not have to recreate all of the component Source objects to produce a Source for the complex query that includes the new selection. Instead, the application just calls the getSource method on the DynamicDefinition for the Template that produces the complex query, and the current state of the changed Template component is used in rebuilding the query.

As an example of using Template objects, suppose an application lets an end user do the following:

• Select a measure, such as sales amount. The sales amount measure has as inputs the products, customers, times, channels, and promotions dimensions.
• Select a dimension, such as products, as the base of the selection of data values to display.
• Specify the number of data values to display, such as 10.
• Specify whether the data values should be from the top or bottom of the range of values, such as top.
• Specify single values for each of the remaining dimensions, such as "San Francisco" for customers, "2000-Q1" for times, "S" for the direct sales channel, and "TV" for promotions.

The data that the user has selected is the ten products that have the highest total sales amounts of those sold through the direct channel to customers from San Francisco in the first quarter of 2000 during a televised promotion.

Suppose the application can use the following objects:

• A MetadataState, called TopBottomTemplateState, that has fields that store values for the measure and the number of data values, the selection of top or bottom, and a selection of single values from the dimensions other than the base.
• A Template, called TopBottomTemplate, that has a method that calls the getCurrentState method on its TopBottomTemplateState, specifies the number of data values, and then calls the setCurrentState method on the TopBottomTemplateState. It has similar methods for specifying the top or bottom and the selection of the measure and the single values for the dimensions other than the base.
• A SourceGenerator, called TopBottomTemplateGenerator, that has methods in its generateSource method that use the values from the TopBottomTemplateState to create a Source.
• A MetadataState, called SingleSelectionsTemplateState, that has fields that stores the measure and the selections of single values from the dimensions.
• A Template, called SingleSelectionsTemplate, that has methods that add the measure and the single value selections to the SingleSelectionsTemplateState.
• A SourceGenerator, called SingleSelectionsTemplateGenerator, that has methods in its generateSource method that use the values from the SingleSelectionsTemplateState to create a Source.

The constructor methods for the SingleSelectionsTemplate and the TopBottomTemplate both do the following:

• Take a DataProvider as an input value.
• Create a new MetadataState and pass it, and the DataProvider, to their Template superclasses.
• Create a new SourceGenerator.
• Create a DynamicDefinition and store it in a private field.

The constructor for the TopBottomTemplate then looks like the following:

public class TopBottomTemplate(DataProvider dataProvider)
  {
  super(new TopBottomTemplateState(),
        dataProvider);
  TopBottomTemplateGenerator topBottomTemplateGenerator =
        new TopBottomTemplateGenerator(dataProvider);
  _definition = createDynamicDefinition(topBottomTemplateGenerator)
  }

Along with a DataProvider, the SingleSelectionsTemplate constructor has as an input value a Source that represents the measure.

The Template subclasses also have a method, called getSource, that calls the getSource method on the saved DynamicDefinition and returns the Source for the Template. After receiving the selections from the end user, the application does the following:

• Creates a new SingleSelectionsTemplate.
• Calls the addSingleValue method on the SingleSelectionsTemplate once for each single value selected for the dimensions other than the base. The method stores the values in fields on the SingleSelectionsTemplateState.
• Calls the getSource method on the SingleSelectionsTemplate.
• Creates a new TopBottomTemplate.
• Calls the methods on the TopBottomTemplate that add the value specifying the number of data values and the value for the selection of top to the TopBottomTemplateState.
• Calls the method on the TopBottomTemplate that adds the Source produced by the SingleSelectionsTemplate to the TopBottomTemplateState.
• Calls the prepareCurrentTransaction and commitCurrentTransaction methods on the TransactionProvider that the application is using.
• Calls the getSource method on the TopBottomTemplate.
• Creates a CursorManagerSpecification for the Source produced by the TopBottomTemplate and then creates a CursorManager and a Cursor.
• Gets the data values from the Cursor to display to the end user.

Suppose that the end user decides to change the single value selection for the customers dimension from "San Francisco" to "Buffalo". The application receives the new selection, and then does the following:

• Calls the addSingleValue method on the SingleSelectionsTemplate, which overwrites the previous value for the dimension that was stored in the SingleSelectionsTemplateState.
• Calls the prepareCurrentTransaction and commitCurrentTransaction methods on the TransactionProvider.
• Calls the getSource method on the TopBottomTemplate.
• Creates a CursorManagerSpecification for the Source produced by the TopBottomTemplate and then creates a CursorManager and a Cursor.
• Ges the values from Cursor and displays them to the end user.

Note that the application does not need to call the getSource method on the SingleSelectionsTemplate. The current state for that Template, with the "Buffalo" selection, is used in the process of generating the Source for the TopBottomTemplate. The application does not need to repeat all of the other steps in producing either of the Template objects.

See Also:

DynamicDefinition, MetadataState, SourceGenerator, TransactionProvider

Template

protected Template(MetadataState initialState,
DataProvider dataProvider)
            throws TransactionTypeUnavailableException,
TransactionInactiveException

Creates a new Template.

Parameters:

initialState - The MetadataState to use with this Template.

dataProvider - A DataProvider for internal use by the Template.

createDynamicDefinition

protected DynamicDefinition createDynamicDefinition(SourceGenerator sourceGenerator)

Creates a DynamicDefinition that acts as a proxy for the SourceDefinition that is immutably paired to the Source generated by the SourceGenerator.

Parameters:

sourceGenerator - The SourceGenerator that generates the Source produced by the current state of this Template.

Returns:

A DynamicDefinition for accessing the Source produced by this Template.

getCurrentState

protected MetadataState getCurrentState()
                                 throws TransactionalObjectInvalidException,
TransactionTypeUnavailableException,
TransactionInactiveException

Gets the current state for this Template.

Returns:

The current state for this Template.

getCurrentStateForRead

protected MetadataState getCurrentStateForRead()
                                        throws TransactionalObjectInvalidException,
TransactionTypeUnavailableException,
TransactionInactiveException

Gets the current state for this Template. Do not modify the state returned by this method; use it only for read operations.

Returns:

The current state for this Template.

getCurrentStateForWrite

protected MetadataState getCurrentStateForWrite()
                                         throws TransactionalObjectInvalidException,
TransactionTypeUnavailableException,
TransactionInactiveException

Gets the current state for this Template. The returned state is a clone of the actual state, so you can modify it. If you modify it, then you must reset the state by passing it to the setCurrentState method.

Returns:

The current state for this Template.

getDataProvider

public DataProvider getDataProvider()

Gets the DataProvider for this Template.

Returns:

The DataProvider with which this Template was constructed.

setCurrentState

protected void setCurrentState(MetadataState state)
                        throws CursorLockException,
WriteLockException,
TransactionTypeUnavailableException,
TransactionInactiveException

Specifies a state as the current state for this Template.

Parameters:

state - The state to specify as the current state for this Template.