Overview of Template and Related Classes

What classes do I use to create a Template?

In the OLAP API, several classes work together to produce a dynamic Source. In designing a Template, you must implement or extend the following:

• The Template abstract class

• The MetadataState interface

• The SourceGenerator interface

Instances of those three classes, plus instances of other classes that the OLAP service creates, work together to produce the Source that the Template defines. The classes that the OLAP service provides, which you create by calling factory methods, are the following:

• DataProvider

• DynamicDefinition

What is the relationship between the classes that produce a dynamic Source?

The classes that produce a dynamic Source work together as follows:

• A 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 that get and set the values of fields on the MetadataState.

• The MetadataState implementation has fields for storing the data to use in generating the Source for the Template. When you create a new Template, you pass the MetadataState to the constructor of the Template. When you call the getSource method on the DynamicDefinition, the MetadataState is passed to the generateSource method on the SourceGenerator.

• The DataProvider is used in creating a Template and by the SourceGenerator in creating new Source objects.

• The SourceGenerator implementation has a generateSource method that uses the current state of the data in the MetadataState to produce a Source for the Template. You pass in the SourceGenerator to the createDynamicDefinition method on the Template to create a DynamicDefinition.

• The DynamicDefinition has a getSource method that gets the Source produced by the SourceGenerator. The DynamicDefinition serves as a proxy for the immutably paired SourceDefinition of that Source.

The following figure illustrates the relationship of the classes described in the preceding list. The arrows on the right indicate that the DataProvider and MetadataState objects are passed to the Template constructor and that the SourceGenerator is passed to the createDynamicDefinition method on the Template. The arrows on the left indicate that a DynamicDefinition is returned by the createDynamicDefinition method and that the same Source is returned by the generateSource method on the SourceGenerator and the getSource method on the DynamicDefinition.

Template class

You use a Template to produce a modifiable Source. A Template has methods for creating a DynamicDefinition and for getting and setting the current state of the Template. In extending the Template class, you add methods that provide access to the fields on the MetadataState for the Template. The Template creates a DynamicDefinition that you use to get the Source produced by the SourceGenerator for the Template.

The Template abstract class implements the following methods:

Method	Return Value
createDynamicDefinition	A DynamicDefinition that is a proxy for the SourceDefinition that is immutably paired to the Source generated by the SourceGenerator passed to this method.
getCurrentState	The current state of the MetadataState for the Template.
setCurrentState	Void. This method specifies the MetadataState passed in as the current state for the Template.

For an example of a Template implementation, see "Example: Implementing a Template".

MetadataState interface

An implementation of the MetadataState interface stores the current state of the values for a Template. A MetadataState must include a clone method that creates a copy of the current state.

When instantiating a new Template, you pass a MetadataState to the Template constructor. The Template has methods for getting and setting the values stored by the MetadataState. The generateSource method on the SourceGenerator for the Template uses the MetadataState when the method produces a Source for the Template.

For an example of a MetadataState implementation, see "Example: Implementing a MetadataState".

SourceGenerator interface

An implementation of SourceGenerator must include a generateSource method, which produces a Source for a Template. A SourceGenerator must produce only one type of Source, such as a BooleanSource, a NumberSource, or a StringSource. In producing the Source, the generateSource method uses the current state of the data represented by the MetadataState for the Template.

To get the Source produced by the generateSource method, you create a DynamicDefinition by passing the SourceGenerator to the createDynamicDefinition method on the Template. You then get the Source by calling the getSource method on the DynamicDefinition.

A Template can create more than one DynamicDefinition, each with a differently implemented SourceGenerator. The generateSource methods on the different SourceGenerator objects use the same data, as defined by the current state of the MetadataState for the Template, to produce Source objects that define different queries.

For an example of a SourceGenerator implementation, see "Example: Implementing a SourceGenerator".

DynamicDefinition class

DynamicDefinition is a subclass of SourceDefinition. You create a DynamicDefinition by calling the createDynamicDefinition method on a Template and passing it a SourceGenerator. You get the Source produced by the SourceGenerator by calling the getSource method on the DynamicDefinition.

A DynamicDefinition created by a Template is a proxy for the SourceDefinition of the Source produced by the SourceGenerator. The SourceDefinition is immutably paired to its Source. If the state of the Template changes, then the Source produced by the SourceGenerator is different. Because the DynamicDefinition is a proxy, you use the same DynamicDefinition to get the new Source even though that Source has a different SourceDefinition.

The getCurrent method of a DynamicDefinition returns the SourceDefinition immutably paired to the Source that the generateSource method currently returns. For an example of the use of a DynamicDefinition, see "Example: Getting the Source produced by the Template".