oracle.olapi.data.cursor
Interface Cursor

All Known Subinterfaces:

CompoundCursor, ValueCursor

public interface Cursor

An interface for objects that provide access to the result set of a query. A query is represented by a Source. A Cursor communicates the query to Oracle OLAP and fetches the result.

At any time, one element of a Cursor is in the current position of the Cursor. The getPosition method returns the current position and the setPosition and next methods change the current position. The extent of a Cursor is the total number of positions of the Cursor.

A Source is created in the context of the current Transaction, which is supplied by a TransactionProvider. A Source is active in the Transaction in which it was created or in a descendent of that Transaction. Before you can create a Cursor for a Source, the following must be true:

• The Source must be active in the current Transaction, that is, the current Transaction must be the one in which the Source was created or it must be a descendent of that Transaction.
• The current Transaction must be a read Transaction.

A derived Source is a Source returned by methods of a Source, such as the join method or the selectValues method. Creating a derived Source occurs in a write Transaction that is a child of a parent read Transaction. The write Transaction begins automatically when you call a method that creates a derived Source. Before you can create a Cursor, you must move the Source from the child write Transaction to the parent read Transaction by calling the prepareCurrentTransaction and commitCurrentTransaction methods of the TransactionProvider that you are using. For more information on transactions, see the TransactionProvider interface.

Creating a Cursor for a Source initially requires the following steps:

1. Create a CursorManagerSpecification by calling the createCursorManagerSpecification method of the DataProvider associated with the Source and passing the Source to that method.
2. Create a CursorManager by calling the createCursorManager method of the DataProvider and passing it the CursorManagerSpecification. If the Source that you used to create the CursorManagerSpecification has an input, then you must add a Source that matches the input to an array of Source objects. Add one Source to the array for each input Source and pass that array as the inputSources parameter of the createCursorManager method.
3. Create a Cursor by calling the createCursor method of the CursorManager. If you have passed a non-null inputSources array to the CursorManager, then you must create a CursorInput for each Source in the inputSources array and pass an array of the CursorInput objects as the cursorInputs parameter of the createCursor method. The order of a CursorInput in the cursorInputs array must be the same order as the Source in the inputSources array for which the CursorInput provides a value.

You can create more than one Cursor from the same CursorManager. You would do this if, for example, you wanted to display different views of the same data.

The following example demonstrates creating a Cursor.

 // Create an MdmMetadataProvider, a DataProvider, and
 // a TransactionProvider for the session.
 // Creating those objects is not shown.
 //
 // Get the MdmSource objects from the MdmMetadataProvider
 // and get Source objects from them.
 // Getting the MdmSource and Source objects is not shown.
 //
 // Define the query as a Source named query.
 // Defining the query is not shown.
 //
 // If query is a derived Source, then prepare and commit the transaction.
 transactionProvider.prepareCurrentTransaction();
 transactionProvider.commitCurrentTransaction();

 // Create a CursorManagerSpecification, a CursorManager, and a Cursor.
 CursorManagerSpecification cursorManagerSpecification =
                dataProvider.createCursorManagerSpecification(query);
 SpecifiedCursorManager cursorManager =
                dataProvider.createCursorManager(cursorManagerSpecification);
 Cursor cursor = cursorManager.createCursor();

The Cursor interface has two subinterfaces: CompoundCursor and ValueCursor. The type of Cursor returned by the createCursor method is determined by the structure of the Source for the Cursor. If the Source for the Cursor has no outputs, then the Cursor has only one set of values and the createCursor method returns a ValueCursor, the elements of which have the values of specified by the Source. If the Source has one or more outputs, then the createCursor method returns a CompoundCursor.

A CompoundCursor has two or more child Cursor objects. The children are the base ValueCursor for the CompoundCursor and the one or more outputs. The CompoundCursor has one output child Cursor for each output of the Source, recursively; that is, if the output of the Source is a Source that itself has one or more outputs, then the child Cursor for that output is another CompoundCursor. If the output is a Source that has no outputs, then the child Cursor is a ValueCursor. Each position of a CompoundCursor specifies a position for each of the ValueCursor objects in the tree of the descendents of the CompoundCursor.

Each Cursor has a corresponding CursorSpecification in its CursorManagerSpecification. If a CursorSpecification is set to calculate the extent of a Cursor or the starting and ending positions of the current value of a child Cursor in its parent Cursor, you can retrieve information with the getExtent, getParentStart, or getParentEnd methods. By subtracting the starting position of the current value of a child in its parent from the ending position of the value and adding one, you can calculate the range of positions, or span, of the value of the child Cursor.

The extent of a child ValueCursor in a parent CompoundCursor is the number of positions the ValueCursor has for the set of values specified by the other ValueCursor descendents. For example, if a Source defines the result set for a measure that has only one value for any set of values of its dimensions, then the ValueCursor that has the values of the measure has only one position for any one set of output values. The extent of that ValueCursor is, therefore, always 1.

The fetch size of a Cursor specifies the number of elements of the Cursor that Oracle OLAP sends to the client application during a single fetch from the data store. If the CursorSpecification for the Cursor is set to specify the default fetch size, you can retrieve the fetch size by calling the getFetchSize method. You can change the fetch size by calling the setFetchSize method.

Some Source objects cannot have a Cursor. You cannot retrieve results with a Cursor for a Source if one of the following is true:

• The Source has an input.
• The Source has no elements or the Source has an input that has no elements.
• The query is not computationally possible; for example, the query involves an infinite recursion.
• The result set is infinite; for example, the Source represents all integers.

Field Summary

static int

FETCH_SIZE_NOT_SPECIFIED A constant value returned by the getDefaultFetchSize method of a CursorSpecification object if the default fetch size is not specified by the CursorSpecification.

Method Summary

long	getExtent() Gets the total number of positions of the Cursor if the CursorSpecification for the Cursor is set to calculate the extent.
int	getFetchSize() Gets the fetch size for the Cursor if the CursorSpecification for the Cursor is set to specify the fetch size.
long	getParentEnd() Gets the position in the parent Cursor at which the current element of the child Cursor ends if the CursorSpecification for the Cursor is set to calculate the ending position.
long	getParentStart() Gets the position in the parent Cursor at which the current element of the child Cursor begins if the CursorSpecification for the Cursor is set to calculate the beginning position.
long	getPosition() Gets the current position of the Cursor.
SourceIdentifier	getSource() Gets the SourceIdentifier for the Cursor.
boolean	next() Advances the position of the Cursor to the next element if the current position is not the last position of the Cursor.
void	setFetchSize(int fetchSize) Specifies the fetch size for the Cursor if the CursorSpecification for the Cursor is set to specify the fetch size.
void	setPosition(long position) Specifies a position to set as the current position of the Cursor.

Field Detail

FETCH_SIZE_NOT_SPECIFIED

public static final int FETCH_SIZE_NOT_SPECIFIED

A constant value returned by the getDefaultFetchSize method of a CursorSpecification object if the default fetch size is not specified by the CursorSpecification.

Method Detail

getSource

public SourceIdentifier getSource()

Gets the SourceIdentifier for the Cursor.

Returns:

The SourceIdentifier for the Cursor.

getPosition

public long getPosition()

Gets the current position of the Cursor.

Returns:

The current position of the Cursor.

setPosition

public void setPosition(long position)
                 throws PositionOutOfBoundsException

Specifies a position to set as the current position of the Cursor.

Parameters:

position - The position to set as the current position of the Cursor.

next

public boolean next()

Advances the position of the Cursor to the next element if the current position is not the last position of the Cursor.

Returns:

true when the method successfully advances the position of the Cursor and false when it does not.

getExtent

public long getExtent()
               throws NotSpecifiedException

Gets the total number of positions of the Cursor if the CursorSpecification for the Cursor is set to calculate the extent. The extent of a ValueCursor that is a descendent in a CompoundCursor is determined by the values of the other outputs.

Returns:

The total number of positions of the Cursor.

getParentStart

public long getParentStart()
                    throws NotSpecifiedException

Gets the position in the parent Cursor at which the current element of the child Cursor begins if the CursorSpecification for the Cursor is set to calculate the beginning position.

Returns:

The position in the parent Cursor at which the current element of the child Cursor begins.

getParentEnd

public long getParentEnd()
                  throws NotSpecifiedException

Gets the position in the parent Cursor at which the current element of the child Cursor ends if the CursorSpecification for the Cursor is set to calculate the ending position.

Returns:

The position in the parent Cursor at which the current element of the child Cursor ends.

getFetchSize

public int getFetchSize()
                 throws NotSpecifiedException

Gets the fetch size for the Cursor if the CursorSpecification for the Cursor is set to specify the fetch size.

Returns:

The fetch size specified for the Cursor.

setFetchSize

public void setFetchSize(int fetchSize)
                  throws NotSpecifiedException

Specifies the fetch size for the Cursor if the CursorSpecification for the Cursor is set to specify the fetch size.

Parameters:

fetchSize - The fetch size to specify for the Cursor.