Cursor Class

Cursor class hierarchy

The Oracle OLAP API defines the following three interfaces in the oracle.olapi.data.cursor package:

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	A 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.

The following figure shows the class hierarchy of the Cursor classes. The CompoundCursor and ValueCursor interfaces extend the Cursor interface.

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.

The following figure illustrates the structure of queryCursor. The top box represents queryCursor, which is the parent CompoundCursor. The bottom row of three boxes represents the three children of queryCursor, which are the base ValueCursor and the two output ValueCursor objects.

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. If you have specified the behavior, you can successfully use the following Cursor methods:

• getExtent

• getFetchSize

• getParentEnd

• getParentStart

• setFetchSize

Before you can use the Cursor methods listed above, you must specify the behavior by calling the following CursorSpecification methods:

• setDefaultFetchSize

• setExtentCalculationSpecified

• setParentEndCalculationSpecified

• setParentStartCalculationSpecified

• specifyDefaultFetchSizeOnChildren
  (for a CompoundCursorSpecification only)

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

• isExtentCalculationSpecified

• isParentEndCalculationSpecified

• isParentStartCalculationSpecified

For examples of specifying Cursor behavior, see Chapter 9. For information on fetch sizes, see "What is the fetch size of a Cursor?". 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".

Cursor methods

All Cursor objects have the following methods:

Method	Return Value
getExtent	The number of elements of the Cursor.
getFetchSize	The fetch size for the Cursor.
getParentEnd	The position of the parent Cursor at which the current value of the child Cursor ends.
getParentStart	The position of the parent Cursor at which the current value of the child Cursor starts.
getPosition	The position of the current element of the Cursor.
getSource	The SourceIdentifier for the Cursor.
next	A boolean that indicates whether an additional element exists in the Cursor and that the current position of the Cursor has advanced to that element.
setFetchSize	Void. This method specifies the fetch size for the Cursor.
setPosition	Void. This method sets the current position of the Cursor.

CompoundCursor methods

In addition to the methods inherited from Cursor, a CompoundCursor has the following methods:

Method	Return Value
getOutputs	A List that contains the outputs of the CompoundCursor.
getValueCursor	The base ValueCursor for the CompoundCursor.

ValueCursor methods

In addition to the methods inherited from Cursor, a ValueCursor has the following methods:

Method	Return Value
getCurrentBoolean	The boolean value at the current position.
getCurrentDate	The Date value at the current position.
getCurrentDouble	The double value at the current position.
getCurrentFloat	The float value at the current position.
getCurrentInteger	The int value at the current position.
getCurrentShort	The short value at the current position.
getCurrentSource	The Source at the current position.
getCurrentString	The String value at the current position.
getCurrentValue	The value at the current position.
hasCurrentValue	A boolean that indicates whether a value exists at the current position.