|
Oracle® OLAP Java API Reference 10g Release 2 (10.2.0.4) B14348-04 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
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:
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.
Transaction must be a read Transaction.
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:
CursorManagerSpecification by calling the
createCursorManagerSpecification method of the
DataProvider associated with the Source
and passing the Source to that method.
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.
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.
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:
Source has an input.
Source has no elements or the Source has an input
that has no elements.
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 |
public static final int FETCH_SIZE_NOT_SPECIFIED
getDefaultFetchSize method
of a CursorSpecification object if the default fetch size is
not specified by the CursorSpecification.
| Method Detail |
public SourceIdentifier getSource()
SourceIdentifier for the Cursor.
SourceIdentifier for the Cursor.public long getPosition()
Cursor.
Cursor.
public void setPosition(long position)
throws PositionOutOfBoundsException
Cursor.
position - The position to set as the current position of the
Cursor.
PositionOutOfBoundsExceptionpublic boolean next()
Cursor to the next element
if the current position is not the last position of the Cursor.
true when the method successfully advances the
position of the Cursor and false when it
does not.
public long getExtent()
throws NotSpecifiedException
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.
Cursor.
NotSpecifiedException
public long getParentStart()
throws NotSpecifiedException
Cursor at which
the current element of the child Cursor begins if the
CursorSpecification for the Cursor is set to
calculate the beginning position.
Cursor at which the
current element of the child Cursor begins.
NotSpecifiedException
public long getParentEnd()
throws NotSpecifiedException
Cursor at which
the current element of the child Cursor ends if the
CursorSpecification for the Cursor is set
to calculate the ending position.
Cursor at which the
current element of the child Cursor ends.
NotSpecifiedException
public int getFetchSize()
throws NotSpecifiedException
Cursor if the
CursorSpecification for the Cursor is set
to specify the fetch size.
Cursor.
NotSpecifiedException
public void setFetchSize(int fetchSize)
throws NotSpecifiedException
Cursor
if the CursorSpecification for the Cursor
is set to specify the fetch size.
fetchSize - The fetch size to specify for the Cursor.
NotSpecifiedException
|
Oracle® OLAP Java API Reference 10g Release 2 (10.2.0.4) B14348-04 |
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||