Cursor Class

In the oracle.olapi.data.cursor package, the Oracle OLAP API defines the interfaces described in the following table.

Interface	Description
Cursor	An abstract superclass that encapsulates the notion of a current position.
ValueCursor	A Cursor that has a value at the current position. A ValueCursor has no child Cursor objects.
CompoundCursor	Cursor that has child Cursor objects, which are a child ValueCursor for the values of its Source and an output child Cursor for each output of the Source.

Figure 8-1shows the class hierarchy of the Cursor classes. The CompoundCursor and ValueCursor interfaces extend the Cursor interface.

Figure 8-1 Cursor Hierarchy

Text description of the illustration cursorhi.gif

Structure of a Cursor

The structure of a Cursor mirrors the structure of its Source. If the Source does not have any outputs, the Cursor for that Source is a ValueCursor. If the Source has one or more outputs, 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.

For example, suppose you have created a derived Source called productSel that represents a selection of product identification values from a primary Source that represents values from a dimension of products. You have selected 815, 1050, and 2055 as the values for productSel. If you create a Cursor for productSel, then that Cursor is a ValueCursor because productSel has no outputs.

You have also created a derived Source called timeSel that represents a selection of day values from a primary Source that represents a dimension of time values. The values of timeSel are 1-JAN-00, 1-APR-00, 1-JUL-00, and 1-OCT-00.

You have an MdmMeasure that represents values for the price of product units. The MdmMeasure has as inputs the MdmDimension objects representing products and times. You get a Source called unitPrice from the measure. The Source has products and times as inputs.

You join productSel and timeSel to unitPrice to create a Source, unitPriceByDay, which has productSel and timeSel as outputs, as in the following:

unitPriceByDay = unitPrice.join(productSel).join(timeSel);

The result set defined by unitPriceByDay is unit price values organized by the outputs. Since timeSel is joined to the result of unitPrice.join(productSel), 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 unitPriceByDay are the fastest varying of all, because there is one price value for each product for each day.

You then create a Cursor, queryCursor, for unitPriceByDay. Since unitPriceByDay 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 unitPriceByDay. The outputs for queryCursor are a ValueCursor that has values from productSel and a ValueCursor that has values from timeSel.

Figure 8-2 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 8-2 Structure of the queryCursor CompoundCursor

Text 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 specified product on the specified day.

Day	Product	Price of Unit
01-JAN-00	815	58
01-JAN-00	1050	24
01-JAN-00	2055	24
01-APR-00	815	59
01-APR-00	1050	24
01-APR-00	2055	25
01-JUL-00	815	59
01-JUL-00	1050	25
01-JUL-00	2055	25
01-OCT-00	815	61
01-OCT-00	1050	25
01-OCT-00	2055	26

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

Specifying the Behavior of a Cursor

The CursorSpecification objects of a CursorManagerSpecification 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, you can successfully use the following Cursor methods:

• getExtent
• getFetchSize
• getParentEnd
• getParentStart
• setFetchSize

For examples of specifying Cursor behavior, see Chapter 9. For information on fetch sizes, see "About Fetch Sizes and Fetch Blocks". 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".