CursorManager Class

About the 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.

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 the OLAP service. 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 find out 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:

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.

The following figure 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.

CursorManager methods

All CursorManager objects have the following methods:

Method	Return Value
addCursorManagerUpdateListener	Void. This method adds a CursorManagerUpdateListener to the CursorManager.
createCursor	A Cursor whose structure is specified by the CursorManagerSpecification of the CursorManager.
isSpecificationUpdateNeeded	A boolean that indicates whether the CursorManager needs to update its CursorManagerSpecification.
removeCursorManagerUpdateListener	Void. This method removes a CursorManagerUpdateListener from the CursorManager.

AbstractCursorManager methods

An AbstractCursorManager implements the following methods of the CursorManager interface:

Method	Return Value
addCursorManagerUpdateListener	Void. This method adds a CursorManagerUpdateListener to the CursorManager.
removeCursorManagerUpdateListener	Void. This method removes a CursorManagerUpdateListener from the CursorManager.

SpecifiedCursorManager methods

A SpecifiedCursorManager has the following methods:

Method	Return Value
close	Void. This method closes the SpecifiedCursorManager and releases the resources associated with it.
isOpen	A boolean that indicates whether the SpecifiedCursorManager is open.
updateSpecification	Void. This method replaces the CursorManagerSpecification of the SpecifiedCursorManager.

ExpressSpecifiedCursorManager methods

In addition to the methods it inherits from AbstractCursorManager, an ExpressSpecifiedCursorManager implements the following methods:

Method	Return Value
close	Void. This method closes the ExpressSpecifiedCursorManager and releases the resources associated with it.
createCursor	A Cursor.
getRemoteStub	A stub for a CORBA object that an application can use in constructing a new ReceiveOnlyCursorManager.
isOpen	A boolean that indicates whether the ExpressSpecifiedCursorManager is open.
isSpecificationUpdateNeeded	A boolean that indicates whether the ExpressSpecifiedCursorManager needs to update its CursorManagerSpecification.
updateSpecification	Void. This method replaces the CursorManagerSpecification for the ExpressSpecifiedCursorManager.