Characteristics of Source Objects

The OLAP API data model is unique. It is not exactly like the relational model or multidimensional model. In the OLAP API, specifications for sets of data that represent the result of queries are represented by instances of the Source class or its subclasses outlined in Table 5-1. Each Source has a paired SourceDefinition that defines the operations that created the query.

Table 5-1  Subclasses of the Source Class

Subclass	Java Type of Values	OLAP API Data Type
BooleanSource	boolean values	Boolean
DateSource	Java Date objects	Date
NumberSource	double, float, int, or short values, or some combination of these numerical values	Double, Float, Integer, Short, or Number
StringSource	Java String objects	String

Source objects are immutable. You cannot change a Source object once it has been created. When you want to present a Source object as changeable to your users, use a Source object defined by a Template object. Template objects have state and can be modified at any time. Using Template objects to make queries is discussed in Chapter 10, "Creating Dynamic Queries".

Source objects are only specifications for a data set; they do not themselves actually have data. Even so, it helps to think of them as the result set they define. From this perspective, a Source knows its type and structure (inputs and outputs).

Source Type

All Source objects have type. In the OLAP API, the type of a Source is another Source from which the Source obtains its values. You can retrieve the type of a Source using the getType method.

The OLAP API provides a FundamentalMetadataObject to represent each of the fundamental Java data type, the Java String object, and the Java Date object. These objects are known as the OLAP API data types. The OLAP API data types of Source objects and their relationship to each other are shown in Table 5-2. You can create a Source object that represents an OLAP API data type by following the process outlined in "Creating Source Objects that Represent OLAP API Data Types" . You can retrieve the OLAP API type of a Source using the getDataType method.

The operation that creates a new Source often determines the type of that Source. For example, assume that you have a Source object named customer whose values are the unique numerical identifier for each customer. The OLAP API type of customer is Integer. Assume, additionally, that you use the select method on customer to create another Source object named customerSelection. The OLAP API type of customerSelection is customer.

Table 5-2 OLAP API Data Types of Source Objects

OLAP API Data Type	Descriptions
Value	A Source object with any OLAP API data type.
Boolean	A Source object whose values have the Java boolean data type.
Date	A Source object whose values are Java Date objects.
Number	A Source object with any of OLAP API numerical data type.
Double	A Source object whose values have the Java double data type.
Float	A Source object whose values have the Java float data type.
Integer	A Source object whose values have the Java int data type.
Short	A Source object whose values have the Java short data type.
String	A Source object whose values are Java String objects.
Empty	A Source object that does not have any values defined for it.
Null	A Source object that has a single null value.

Source Structure: Inputs and Outputs

All Source objects (except for an empty Source) have values. In some cases, the values of a Source are unique data items that are meaningful unto themselves. If you are familiar with relational concepts, you can conceptualize this type of Source as a table with a single column -- the column that contains the values of the Source. If you are more familiar with multidimensional concepts, you can conceptualize this type of Source as a dimension.

In other cases, the values of a Source are not unique data items and, thus, are not meaningful unto themselves. Instead the values of the Source are meaningful only in relationship to the values of another Source. In this case, the structure of the Source is determined by other Source objects called inputs and outputs. Whether one of these other Source objects is an input or an output is determined by whether or not values have been specified for it:

• Outputs. When values have been specified, the other Source object is called an output. The values of a Source are identified by the set of its output values. You can retrieve the outputs of a Source using the getOutputs method.
• Inputs. When values have not been specified, the other Source object is called an input. A Source that has inputs is an indeterminable result set. If you are familiar with relational concepts, you think of an input as a column that acts as a key to the values of a Source, but that is in the GROUP BY list of a SQL statement. If you are more familiar with multidimensional concepts, you can conceptualize an input that is a dimension of a Source, but that is not in its dimension list. You can retrieve the inputs of a Source using the getInputs method.

The inputs and outputs of a Source determine how the Source is processed by Oracle OLAP. For example, when a Cursor is opened on a Source, Oracle OLAP loops over its outputs in order to produce the data, but it (arbitrarily) qualifies away any of its inputs. In order to retrieve one or more values of a Source with inputs, you must specify the values for its inputs that will uniquely identify the desired values of the Source. The order in which you specify values for the inputs determines the structure and processing of a Source. The input that you specify values for first becomes the slowest-varying output. For more information on specifying values for inputs, see "Selecting Based on Output Values" and "Effect of Input-Output Order on Source Structure".

Additionally, when a Source has both inputs and outputs, the values of the Source are identified by the set of its output value and each set of possible output values typically identifies a number of values (that is, a subset of data). Some Source methods work on these subsets of data. For example, Oracle OLAP loops over the outputs of a Source when it processes any methods that select values based on their positions (the first value of each subset has a position of 1) or any aggregation methods like average and total. For an in-depth discussions of the positional and aggregation methods, see "Finding the Position of Values" and "Working with Aggregation Methods" ,