9 Understanding Cursor Classes and Concepts

9.1.1 Creating a Cursor Using a CursorManagerSpecification

In the older method, after creating a Source that defines the data that you want to retrieve from the data store, you create a Cursor for that Source by doing the following:

1. Creating a CursorManagerSpecification by passing the Source to the createCursorManagerSpecification method of the DataProvider that you are using. The CursorManagerSpecification has CursorSpecification objects in a structure that mirrors the structure of the Source.

2. Creating a CursorManager by calling the createCursorManager method of the DataProvider and passing it the CursorManagerSpecification. The CursorManager creates Cursor objects. It also manages the local data cache for its Cursor objects and is aware of changes to the Source for a dynamic query or a parameterized Source. If the Source for the CursorManagerSpecification has inputs, then you must also pass to the createCursorManager method an array of Source objects for those inputs.

3. Creating a Cursor by calling the createCursor method of the CursorManager. The structure of the Cursor mirrors the structures of the CursorManagerSpecification and the Source. The CursorSpecification objects of a CursorManagerSpecification specify the behavior of their corresponding Cursor objects. If the Source for the CursorManagerSpecification has inputs, then you must also pass to the createCursor method an array of CursorInput objects that specify values for the input Source objects.

For an example of creating a Cursor using this method, see Chapter 10.

This architecture provides great flexibility in fetching data from a result set and in selecting data to display. You can do the following:

• Create more than one CursorManagerSpecification object for the same Source. You can specify different behavior on the CursorSpecification components of the various CursorManagerSpecification objects in order to retrieve and display different sets of values from the same result set. You might want to do this when displaying the data from a Source in different formats, such as in a table and a crosstab.

• Receive notification that the Source produced by the Template has changed. If you add a CursorManagerUpdateListener to the CursorManager for a Source, then the CursorManager notifies the CursorManagerUpdateListener when the Source for a dynamic query has changed and you that therefore need to update the CursorManagerSpecification for the CursorManager.

• Update the CursorManagerSpecification for a CursorManager. If you are using Template objects to produce a dynamic query and the state of a Template changes, then the Source produced by the Template changes. If you have created a Cursor for the Source produced by the Template, then you need to replace the CursorManagerSpecification for the CursorManager with an updated CursorManagerSpecification for the changed Source. You can then create a new Cursor from the CursorManager.

• Create different Cursor objects from the same CursorManager and set different fetch sizes on those Cursor objects. You might do this when you want to display the same data as a table and as a graph.

This older method of creating a CursorManager returns an ExpressSpecifiedCursorManager.

9.1.2 Creating a Cursor Without a CursorManagerSpecification

In the newer method, you create a Cursor for a Source by doing the following:

1. Creating a CursorManager by calling one of the createCursorManager methods of the DataProvider and passing it the Source. If you want to alter the behavior of the Cursor, then you can create a CursorInfoSpecification and use its methods to specify the behavior. You then create a CursorManager with a method that takes the Source and the CursorInfoSpecification.

2. Creating a Cursor by calling the createCursor method of the CursorManager.

This newer method of creating a CursorManager returns an ExpressDataCursorManager.

9.1.3 Sources For Which You Cannot Create a Cursor

Some Source objects do not specify data that a Cursor can retrieve from the data store. The following are Source objects for which you cannot create a Cursor.

• A Source that specifies an operation that is not computationally possible. An example is a Source that specifies an infinite recursion.

• A Source that defines an infinite result set. An example is the fundamental Source that represents the set of all String objects.

• A Source that has no elements or includes another Source that has no elements. Examples are a Source returned by the getEmptySource method of DataProvider and another Source derived from the empty Source. Another example is a derived Source that results from selecting a value from a primary Source that you got from an MdmDimension and the selected value does not exist in the dimension.

9.1.4 Cursor Objects and Transaction Objects

When you create a derived Source or change the state of a Template, you create the Source in the context of the current Transaction. The Source is active in the Transaction in which you create it or in a child Transaction of that Transaction. A Source must be active in the current Transaction for you to be able to create a Cursor for it.

Creating a derived Source occurs in a write Transaction. Creating a Cursor occurs in a read Transaction. After creating a derived Source, and before you can create a Cursor for that Source, you must change the write Transaction into a read Transaction by calling the prepareCurrentTransaction and commitCurrentTransaction methods of the TransactionProvider your application is using. For information on Transaction and TransactionProvider objects, see Chapter 8, " Using a TransactionProvider".

For a Cursor that you create for a query that includes a parameterized Source, you can change the value of the Parameter object and then get the new values of the Cursor without having to prepare and commit the Transaction again. For information on parameterized Source objects, see Chapter 6, " Understanding Source Objects".

9.2.1 Structure of a Cursor

The structure of a Cursor mirrors the structure of its Source. If the Source does not have any outputs, then the Cursor for that Source is a ValueCursor. If the Source has one or more outputs, then the Cursor for that Source is a CompoundCursor. A CompoundCursor has as children a base ValueCursor, which has the values of the base of the Source of the CompoundCursor, and one or more output Cursor objects.

The output of a Source is another Source. An output Source can itself have outputs. The child Cursor for an output of a Source is a ValueCursor if the output Source does not have any outputs and a CompoundCursor if it does.

Example 9-1 creates a query that specifies the prices of selected product items for selected months. In the example, timeHier is a Source for a hierarchy of a dimension of time values, and prodHier is a Source for a hierarchy of a dimension of product values.

If you create a Cursor for prodSel or for timeSel, then either Cursor is a ValueCursor because both prodSel and timeSel have no outputs.

The unitPrice object is a Source for an MdmMeasure that represents values for the price of product units. The MdmMeasure has as inputs the MdmPrimaryDimension objects representing products and times, and the unitPrice Source has as inputs the Source objects for those dimensions.

The example selects elements of the dimension hierarchies and then joins the Source objects for the selections to that of the measure to produce querySource, which has prodSel and timeSel as outputs.

Source timeSel = timeHier.selectValues(new String[] 
                                          {"CALENDAR::MONTH::55",
                                           "CALENDAR::MONTH::58",
                                           "CALENDAR::MONTH::61",
                                           "CALENDAR::MONTH::64"});
 
Source prodSel = prodHier.selectValues(new String[]
                                          {"PRODUCT_ROLLUP::ITEM::13",
                                           "PRODUCT_ROLLUP::ITEM::14",
                                           "PRODUCT_ROLLUP::ITEM::15"});
 
Source querySource = unitPrice.join(prodSel).join(timeSel);

The result set defined by querySource is the unit price values for the selected products for the selected months. The results are organized by the outputs. Since timeSel is joined to the Source produced by the unitPrice.join(prodSel) operation, timeSel is the slower varying output, which means that the result set specifies the set of selected products for each selected time value. For each time value the result set has three product values so the product values vary faster than the time values. The values of the base ValueCursor of querySource are the fastest varying of all, because there is one price value for each product for each day.

Example 10-1 in Chapter 10, creates a Cursor, queryCursor, for querySource. Since querySource has outputs, queryCursor is a CompoundCursor. The base ValueCursor of queryCursor has values from unitPrice, which is the base Source of the operation that created querySource. The values from unitPrice are those specified by the outputs.The outputs for queryCursor are a ValueCursor that has values from prodSel and a ValueCursor that has values from timeSel.

Figure 9-1 illustrates the structure of queryCursor. The base ValueCursor and the two output ValueCursor objects are the children of queryCursor, which is the parent CompoundCursor.

Figure 9-1 Structure of the queryCursor CompoundCursor

Description of the illustration qrycrstr.gif

The following table displays the values from queryCursor in a table. The left column has time values, the middle column has product values, and the right column has the unit price of the product for the month.

For examples of getting the values from a ValueCursor, see Chapter 10.

9.2.2 Specifying the Behavior of a Cursor

CursorSpecification objects specify some aspects of the behavior of their corresponding Cursor objects. You must specify the behavior on a CursorSpecification before creating the corresponding Cursor. To specify the behavior, use the following CursorSpecification methods:

• setDefaultFetchSize

• setExtentCalculationSpecified

• setParentEndCalculationSpecified

• setParentStartCalculationSpecified

• specifyDefaultFetchSizeOnChildren
  (for a CompoundCursorSpecification only)

A CursorSpecification also has methods that you can use to discover if the behavior is specified. Those methods are the following:

• isExtentCalculationSpecified

• isParentEndCalculationSpecified

• isParentStartCalculationSpecified

If you have used the CursorSpecification methods to set the default fetch size, or to calculate the extent or the starting or ending positions of a value in its parent, then you can successfully use the following Cursor methods:

• getExtent

• getFetchSize

• getParentEnd

• getParentStart

• setFetchSize

For examples of specifying Cursor behavior, see Chapter 10. For information on fetch sizes, see "About Fetch Sizes". For information on the extent of a Cursor, see "What is the Extent of a Cursor?". For information on the starting and ending positions in a parent Cursor of the current value of a Cursor, see "About the Parent Starting and Ending Positions in a Cursor".

9.5.1 Updating the CursorManagerSpecification for a CursorManager

If your application is using OLAP API Template objects and the state of a Template changes in a way that alters the structure of the Source produced by the Template, then any CursorManagerSpecification objects for the Source are no longer valid. You need to create new CursorManagerSpecification objects for the changed Source.

After creating a new CursorManagerSpecification, you can create a new CursorManager for the Source. You do not, however, need to create a new CursorManager. You can call the updateSpecification method of the existing CursorManager to replace the previous CursorManagerSpecification with the new CursorManagerSpecification. You can then create a new Cursor from the CursorManager.

To determine whether the CursorManagerSpecification for a CursorManager needs updating, call the isSpecificationUpdateNeeded method of the CursorManager. You can also use a CursorManagerUpdateListener to listen for events generated by changes in a Source. For more information, see "CursorManagerUpdateListener Class" .

9.6.1 CursorInput Class

For Oracle OLAP in Oracle Database 10g, the OLAP API includes Parameter classes, which are more convenient than CursorInput objects. With a Parameter, you can create a parameterized Source. You can create a CursorManagerSpecification for a query that includes a parameterized Source, and then create a CursorManager and a Cursor.

You can then change the value of the Parameter, which changes the selection of dimension or measure elements specified by the parameterized Source. The Cursor for the query then has the new set of values for the changed query. You do not need to prepare and commit the Transaction again before getting the values of the Cursor. For information on parameterized Source objects, see Chapter 6, " Understanding Source Objects".

A CursorInput provides a value for a Source that you include in the array of Source objects that is the inputSources argument to the createCursorManager method of a DataProvider. If you create a CursorManagerSpecification for a Source that has one or more inputs, then you must provide an inputSources argument when you create a CursorManager for that CursorManagerSpecification. You include a Source in the inputSources array for each input of the Source that you pass to the createCursorManagerSpecification method.

When you create a CursorInput object, you can specify either a single value or a ValueCursor. If you specify a ValueCursor, then you can call the synchronize method of the CursorInput to make the value of the CursorInput be the current value of the ValueCursor.

9.6.2 CursorManagerUpdateListener Class

CursorManagerUpdateListener is an interface that has methods that receive CursorManagerUpdateEvent object. Oracle OLAP generates a CursorManagerUpdateEvent object in response to a change that occurs in a Source that is produced by a Template or when a CursorManager updates its CursorManagerSpecification. Your application can use a CursorManagerUpdateListener to listen for events that indicate it might need to create new Cursor objects from the CursorManager or to update its display of data from a Cursor.

To use a CursorManagerUpdateListener, implement the interface, create an instance of the class, and then add the CursorManagerUpdateListener to the CursorManager for a Source. When a change to the Source occurs, the CursorManager calls the appropriate method of the CursorManagerUpdateListener and passes it a CursorManagerUpdateEvent. Your application can then perform the tasks needed to generate new Cursor objects and update the display of values from the result set that the Source defines.

You can implement more than one version of the CursorManagerUpdateListener interface. You can add instances of them to the same CursorManager.

9.6.3 CursorManagerUpdateEvent Class

Oracle OLAP generates a CursorManagerUpdateEvent object in response to a change that occurs in a Source that is produced by a Template or when a CursorManager updates its CursorManagerSpecification.

You do not directly create instances of this class. Oracle OLAP generates CursorManagerUpdateEvent objects and passes them to the appropriate methods of any CursorManagerUpdateListener objects you have added to a CursorManager. The CursorManagerUpdateEvent has a field that indicates the type of event that occurred. A CursorManagerUpdateEvent has methods you can use to get information about it.

9.7.1 Positions of a ValueCursor

The current position of a ValueCursor specifies a value, which you can retrieve. For example, prodSel, a derived Source described in "Structure of a Cursor" , is a selection of three products from a primary Source that specifies a dimension of products and their hierarchical groupings. The ValueCursor for prodSel has three elements. The following example gets the position of each element of the ValueCursor, and displays the value at that position. The context object has a method that displays text.

// prodSelValCursor is the ValueCursor for prodSel
context.println("ValueCursor Position  Value ");
context.println("--------------------  ------------------------ ");
do 
{
  context.println("          " + prodSelValCursor.getPosition() + 
                  "           " + prodSelValCursor.getCurrentValue());
} while(prodSelValCursor.next());

The preceding example displays the following:

ValueCursor Position  Value 
--------------------  ------------------------ 
          1           PRODUCT_ROLLUP::ITEM::13
          2           PRODUCT_ROLLUP::ITEM::14
          3           PRODUCT_ROLLUP::ITEM::15

The following example sets the current position of prodSelValCursor to 2 and retrieves the value at that position.

prodSelValCursor.setPosition(2);
context.println(prodSelValCursor.getCurrentString());

The preceding example displays the following:

PRODUCT_ROLLUP::ITEM::14

For more examples of getting the current value of a ValueCursor, see Chapter 10.

9.7.2 Positions of a CompoundCursor

A CompoundCursor has one position for each set of the elements of its descendent ValueCursor objects. The current position of the CompoundCursor specifies one of those sets.

For example, querySource, the Source created in Example 9-1, has values from a measure, unitPrice. The values are the prices of product units at different times. The outputs of querySource are Source objects that represent selections of four month values from a time dimension and three product values from a product dimension.

The result set for querySource has one measure value for each tuple (each set of output values), so the total number of values is twelve (one value for each of the three products for each of the four months). Therefore, the queryCursor CompoundCursor created for querySource has twelve positions.

Each position of queryCursor specifies one set of positions of its outputs and its base ValueCursor. For example, position 1 of queryCursor defines the following set of positions for its outputs and its base ValueCursor:

• Position 1 of output 1 (the ValueCursor for timeSel)

• Position 1 of output 2 (the ValueCursor for prodSel)

• Position 1 of the base ValueCursor for queryCursor (This position has the value from the unitPrice measure that is specified by the values of the outputs.)

Figure 9-2 illustrates the positions of queryCursor CompoundCursor, its base ValueCursor, and its outputs.

Figure 9-2 Cursor Positions in queryCursor

Description of the illustration qrycrspo.gif

The ValueCursor for queryCursor has only one position because only one value of unitPrice is specified by any one set of values of the outputs. For a query like querySource, the ValueCursor of its Cursor has only one value, and therefore only one position, at a time for any one position of the root CompoundCursor.

Figure 9-3 illustrates one possible display of the data from queryCursor. It is a crosstab view with four columns and five rows. In the left column are the month values. In the top row are the product values. In each of the intersecting cells of the crosstab is the price of the product for the month.

Figure 9-3 Crosstab Display of queryCursor

Description of the illustration xtabvudp.gif

A CompoundCursor coordinates the positions of its ValueCursor objects relative to each other. The current position of the CompoundCursor specifies the current positions of its descendent ValueCursor objects. Example 9-2 sets the position of queryCursor and then gets the current values and the positions of the child Cursor objects.

CompoundCursor rootCursor = (CompoundCursor) queryCursor;
ValueCursor baseValueCursor = rootCursor.getValueCursor();
List outputs = rootCursor.getOutputs();
ValueCursor output1 = (ValueCursor) outputs.get(0);
ValueCursor output2 = (ValueCursor) outputs.get(1);
int pos = 5;
rootCursor.setPosition(pos);
System.out.println("CompoundCursor position set to " + pos + ".");
System.out.println("The current position of the CompoundCursor is = "
                    + rootCursor.getPosition() + ".");
System.out.println("Output 1 position = " + output1.getPosition() +
                   ", value = " + output1.getCurrentValue());
System.out.println("Output 2 position = " + output2.getPosition() +
                   ", value = " + output2.getCurrentValue());
System.out.println("VC position = " + baseValueCursor.getPosition() +
                   ", value = " + baseValueCursor.getCurrentValue());

CompoundCursor position set to 5.
The current position of the CompoundCursor is 5.
Output 1 position = 2, value = CALENDAR::MONTH::58
Output 2 position = 2, value = PRODUCT_ROLLUP::ITEM::14
VC position = 1, value = 3107.65

// Create the query
querySource2 = prodSel.join(unitPrice).join(timeSel);
 
// Prepare and commit the current Transaction.
try
{
  tp.prepareCurrentTransaction();
}
catch(NotCommittableException e)
{
  output.println("Cannot commit current Transaction " + e);
}
tp.commitCurrentTransaction();

// Create the Cursor. The DataProvider is dp.
CursorManagerSpecification cursorMngrSpec = 
                  dp.createCursorManagerSpecification(querySource2);
CursorManager cursorManager = dp.createCursorManager(cursorMngrSpec);
Cursor queryCursor2 = cursorManager.createCursor();

CompoundCursor rootCursor = (CompoundCursor) queryCursor2;
ValueCursor baseValueCursor = rootCursor.getValueCursor();
List outputs = rootCursor.getOutputs();
ValueCursor output1 = (ValueCursor) outputs.get(0);

// Get the positions and values and display them.
System.out.println("CompoundCursor Output ValueCursor" +
                   "    ValueCursor");
System.out.println("  position      position | value  " +
                   "position | value");
do
{
System.out.println("      " + rootCursor.getPosition() +
               "             " + output1.getPosition() +
               "       " + getLocalValue(output1.getCurrentString()) +
               "       " + baseValueCursor.getPosition() +  "       " 
                 + getLocalValue(baseValueCursor.getCurrentString()));
}
while(queryCursor2.next());

CompoundCursor Output ValueCursor   ValueCursor
  position      position | value  position | value
      1             1       55       1       13
      2             1       55       2       14
      3             1       55       3       15
      4             2       58       1       15
      5             3       61       1       14
      6             3       61       2       15
      7             4       64       1       13
      8             4       64       2       14

Because not every combination of product and time selections has unit sales greater than 1 for the specified channel and customer selections, the number of elements of the ValueCursor for the values derived from prodSel is not the same for each value of the output ValueCursor. For time value 55, all three products have sales greater than one, but for time value 58, only one of the products does. The other two time values, 61 and 64, have two products that meet the criteria. Therefore, the ValueCursor for the CompoundCursor has three positions for time 55, only one position for time 58, and two positions for times 61 and 64.

9.7.3 About the Parent Starting and Ending Positions in a Cursor

To effectively manage the display of the data that you get from a CompoundCursor, you sometimes need to know how many faster varying values exist for the current slower varying value. For example, suppose that you are displaying in a crosstab one row of values from an edge of a cube, then you might want to know how many columns to draw in the display for the row.

To determine how many faster varying values exist for the current value of a child Cursor, you find the starting and ending positions of that current value in the parent Cursor. Subtract the starting position from the ending position and then add 1, as in the following.

long span = (cursor.getParentEnd() - cursor.getParentStart()) + 1;

The result is the span of the current value of the child Cursor in its parent Cursor, which tells you how many values of the fastest varying child Cursor exist for the current value. Calculating the starting and ending positions is costly in time and computing resources, so you should only specify that you want those calculations performed when your application needs the information.

An Oracle OLAP API Cursor enables your application to have only the data that it is currently displaying actually present on the client computer. For information on specifying the amount of data for a Cursor, see "About Fetch Sizes".

From the data on the client computer, however, you cannot determine at what position of its parent Cursor the current value of a child Cursor begins or ends. To get that information, you use the getParentStart and getParentEnd methods of a Cursor.

For example, suppose your application has a Source named cube that represents a cube that has an asymmetric edge. The cube has four outputs. The cube Source defines products with unit sales greater than one purchased by a certain customers during three months of the year 2001. The products were sold through the direct sales channel.

You create a Cursor for that Source and call it cubeCursor. The CompoundCursor cubeCursor has the following child Cursor objects:

• output 1, a ValueCursor for the channel values

• output 2, a ValueCursor for the time values

• output 4, a ValueCursor for the customer values

• The base ValueCursor, which has values that are the products with unit sales greater than one.

Figure 9-4 illustrates the parent, cubeCursor, with the values of its child Cursor objects layered horizontally. The slowest varying output, with the channel value, is at the top and the fastest varying child, with the product values, is at the bottom. The only portion of the edge that you are currently displaying in the user interface is the block between positions 9 and 12 of cubeCursor, which is shown within the bold border. The positions, 1 through 15, of cubeCursor appear over the top row.

Figure 9-4 Values of the ValueCursor Children of cubeCursor

Description of the illustration cubcrsvl.gif

The current value of the output ValueCursor for the time Source is 44. You cannot determine from the data within the block that the starting and ending positions of the current value, 44, in the parent, cubeCursor, are 5 and 9, respectively.

The cubeCursor from the previous figure is shown again in Figure 9-5, this time with the range of the positions of the parent, cubeCursor, for each of the values of the child Cursor objects. By subtracting the smaller value from the larger value and adding one, you can compute the span of each value. For example, the span of the time value 44 is (9 - 5 + 1) = 5.

Figure 9-5 The Range of Positions of the Child Cursor Objects of cubeCursor

Description of the illustration cubcrsrn.gif

To specify that you want Oracle OLAP to calculate the starting and ending positions of a value of a child Cursor in its parent Cursor, call the setParentStartCalculationSpecified and setParentEndCalculationSpecified methods of the CursorSpecification corresponding to the Cursor. You can determine whether calculating the starting or ending positions is specified by calling the isParentStartCalculationSpecified or isParentEndCalculationSpecified methods of the CursorSpecification. For an example of specifying these calculations, see Chapter 10.

9.7.4 What is the Extent of a Cursor?

The extent of a Cursor is the total number of elements it contains relative to any slower varying outputs. Figure 9-6 illustrates the number of positions of each child Cursor of cubeCursor relative to the value of its slower varying output. The child Cursor objects are layered horizontally with the slowest varying output at the top.

The total number of elements in cubeCursor is fifteen so the extent of cubeCursor is therefore fifteen. That number is over the top row of the figure. The top row is the ValueCursor for the channel value. The extent of the ValueCursor for channel values is one because it has only one value.

The second row down is the ValueCursor for the time values. Its extent is 3, since there are 3 months values. The next row down is the ValueCursor for the customer values. The extent of its elements depends on the value of the slower varying output, which is time. The extent of the customers ValueCursor for the first month is two, for the second month it is two, and for the third month it is three.

The bottom row is the base ValueCursor for the cubeCursor CompoundCursor. Its values are products. The extent of the elements of the products ValueCursor depends on the values of the customers ValueCursor and the time ValueCursor. For example, since three products values are specified by the first set of month and customer values (products 13, 14, and 15 for customer 58 for time 43), the extent of the products ValueCursor for that set is 3. For the second set of values for customers and times (customer 61 for time 43), the extent of the products ValueCursor is 1, and so on.

Figure 9-6 The Number of Elements of the Child Cursor Objects of cubeCursor

Description of the illustration cubcrspo.gif

The extent is information that you can use, for example, to display the correct number of columns or correctly-sized scroll bars. The extent, however, can be expensive to calculate. For example, a Source that represents a cube might have four outputs. Each output might have hundreds of values. If all null values and zero values of the measure for the sets of outputs are eliminated from the result set, then to calculate the extent of the CompoundCursor for the Source, Oracle OLAP must traverse the entire result space before it creates the CompoundCursor. If you do not specify that you wants the extent calculated, then Oracle OLAP only needs to traverse the sets of elements defined by the outputs of the cube as specified by the fetch size of the Cursor and as needed by your application.

To specify that you want Oracle OLAP to calculate the extent for a Cursor, call the setExtentCalculationSpecified method of the CursorSpecification corresponding to the Cursor. You can determine whether calculating the extent is specified by calling the isExtentCalculationSpecified method of the CursorSpecification. For an example of specifying the calculation of the extent of a Cursor, see Chapter 10.