CursorManagerSpecification Class

A CursorManagerSpecification for a Source has one or more CursorSpecification objects. The structure of those objects reflects the structure of the Source. For example, a Source that has outputs has a top-level, or root, CursorSpecification for the Source, a child CursorSpecification for the values of the Source, and a child CursorSpecification for each output of the Source.

A Source that does not have any outputs has only one set of values. A CursorManagerSpecification for that Source therefore has only one CursorSpecification. That CursorSpecification is the root CursorSpecification of the CursorManagerSpecification.

You can create a CursorManagerSpecification for a multidimensional Source that has one or more inputs. If you do so, then you need to supply a Source for each input when you create a CursorManager for the CursorManagerSpecification. You must also supply a CursorInput for each input Source when you create a Cursor from the CursorManager. You might create a CursorManagerSpecification for a Source with inputs if you want to use a CursorManager to create a series of Cursor objects with each Cursor retrieving data specified by a different set of single values for the input Source objects.

The structure of a Cursor reflects the structure of its CursorManagerSpecification. A Cursor can be a single ValueCursor, for a Source with no outputs, or a CompoundCursor with child Cursor objects, for a Source with outputs. Each Cursor corresponds to a CursorSpecification in the CursorManagerSpecification. You use CursorSpecification methods to specify aspects of the behavior of the corresponding Cursor.

If your application uses Template objects, and a change occurs in the state of a Template so that the structure of the Source produced by the Template changes, then any CursorManagerSpecification objects that the application created for the Source expire. If a CursorManagerSpecification expires, you must create a new CursorManagerSpecification. You can then either use the new CursorManagerSpecification to replace the old CursorManagerSpecification of a CursorManager or use it to create a new CursorManager. You can discover if a CursorManagerSpecification has expired by calling the isExpired method on the CursorManagerSpecification.

CursorSpecification Class

A CursorSpecification specifies certain aspects of the behavior of the Cursor that corresponds to it. You do not create a CursorSpecification directly. You pass a Source to the createCursorManagerSpecification method of a DataProvider and the CursorManagerSpecification returned has a root CursorSpecification for that Source. If the Source has outputs, the CursorManagerSpecification also has a child CursorSpecification for the values of the Source and one for each output of the Source.

With CursorSpecification methods, you can do the following:

• Get the Source that corresponds to the CursorSpecification.
• Get or set the default fetch size for the corresponding Cursor.
• On a CompoundCursorSpecification, specify that the default fetch size is set on the children of the corresponding Cursor.
• Specify that Oracle OLAP should calculate the extent of a Cursor.
• Determine if calculating the extent is specified.
• Specify that Oracle OLAP should calculate the starting or ending position of the current value of the corresponding Cursor in its parent Cursor. If you know the starting and ending positions of a value in the parent, then you can determine how many faster varying elements the parent Cursor has for that value.
• Determine if calculating the starting or ending position of the current value of the corresponding Cursor in its parent is specified.
• Accept a CursorSpecificationVisitor.

For more information, see "About Cursor Positions and Extent" and "About Fetch Sizes and Fetch Blocks".

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

Class	Description
CursorSpecification	An abstract superclass that implements methods inherited by its subclasses.
ValueCursorSpecification	A CursorSpecification for a Source that has values and no outputs.
CompoundCursorSpecification	A CursorSpecification for a Source that has one or more outputs. A CompoundCursorSpecification has component child CursorSpecification objects.

A Cursor has the same structure as its CursorManagerSpecification. For every ValueCursorSpecification or CompoundCursorSpecification of a CursorManagerSpecification, a Cursor has a corresponding ValueCursor or CompoundCursor. To be able to get certain information or behavior from a Cursor, your application must specify that it wants that information or behavior by calling methods on the corresponding CursorSpecification before it creates the Cursor.

CursorInput Class

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 on 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, you can call the synchronize method on the CursorInput to make the value of the CursorInput be the current value of the ValueCursor.

CursorManager Class

A CursorManager manages the buffering of data for the Cursor objects it creates. To create a CursorManager, call the createCursorManager method on a DataProvider and pass it a CursorManagerSpecification. If the Source for the CursorManagerSpecification has one or more inputs, then also pass an array of Source objects to the createCursorManager method. Include in the array a Source for each input.

You can create more than one Cursor from the same CursorManager, which is useful for displaying data from a result set in different formats such as a table or a graph. All of the Cursor objects created by a CursorManager have the same specifications, such as the default fetch sizes and the levels at which fetch sizes are set. Because the Cursor objects have the same specifications, they can share the data managed by the CursorManager.

A CursorManager has methods for creating a Cursor, for discovering whether the CursorManagerSpecification for the CursorManager needs updating, and for adding or removing a CursorManagerUpdateListener. The SpecifiedCursorManager interface adds methods for updating the CursorManagerSpecification, for discovering if the SpecifiedCursorManager is open, and for closing it. The createCursorManager method on DataProvider returns an implementation of the SpecifiedCursorManager interface.

When your application no longer needs a SpecifiedCursorManager, it should close it to free resources in the application and in Oracle OLAP. To close the SpecifiedCursorManager, call its close method.

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 on the existing CursorManager to replace the previous CursorManagerSpecification with the new CursorManagerSpecification. You can then create a new Cursor from the CursorManager.

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

CursorManager Class Hierarchy

The following table lists most of the CursorManager interfaces and classes.

Interface or Class	Description
CursorManager	An interface that has defines methods for all CursorManager objects.
AbstractCursorManager	A CursorManager that implements methods for adding and removing CursorManagerUpdateListener objects. For more information, see "CursorManagerUpdateListener Class" .
SpecifiedCursorManager	An interface that defines additional methods for a CursorManager.
ExpressSpecifiedCursorManager	A class that implements the SpecifiedCursorManager interface and extends AbstractCursorManager. In the Oracle OLAP API, the createCursorManager method on DataProvider returns an instance of this class.

Figure 8-3 shows the relationships of the CursorManager classes described in the preceding table. A solid line and a closed arrowhead indicate that a class extends the class to which the arrow points. A dotted line and an open arrowhead indicate that the class implements the interface to which the arrow points.

Figure 8-3 CursorManager Hierarchy

Text description of the illustration crsmgrhi.gif

CursorManagerUpdateListener Class

CursorManagerUpdateListener is an interface that has methods that receive CursorManagerUpdateEvent objects. 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 on 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.

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.