oracle.olapi.data.source
Class CursorSpecification

java.lang.Object
  |
  +--oracle.olapi.data.source.CursorSpecification

Direct Known Subclasses:

CompoundCursorSpecification, ValueCursorSpecification

public abstract class CursorSpecification

extends java.lang.Object

implements CursorInfoSpecification

An object that specifies characteristics of a Cursor. A CursorSpecification is created in the context of a CursorManagerSpecification. When a DataProvider creates a CursorManagerSpecification for a Source, one CursorSpecification is created for the values of the elements of the Source and one for each output of the Source, if any, recursively; that is, if the output of the Source is a Source that itself has one or more outputs, then the CursorManagerSpecification has a CursorSpecification for the values of the output Source and one for each of the outputs of that Source.

After creating a CursorManagerSpecification, an application can create a CursorManager by passing the CursorManagerSpecification to the createCursorManager method of the DataProvider. The application can then create a Cursor by calling the createCursor method of the CursorManager. The structure of that Cursor mirrors the structure of the CursorSpecification objects of the CursorManagerSpecification.

A CursorSpecification can be a ValueCursorSpecification, which represents the values of the Source, or a CompoundCursorSpecification, which represents a Source with one or more outputs. For example, suppose an application has an MdmPrimaryDimension that represents a list of products. The application gets a Source from the MdmPrimaryDimension and names it productDim. The elements of productDim have values that are String objects. The application calls the createCursorManagerSpecification method of a DataProvider and passes productDim to the method. The CursorManagerSpecification returned by the method has only one CursorSpecification, a ValueCursorSpecification for the values of productDim. That ValueCursorSpecification is the root CursorSpecification of the CursorManagerSpecification.

A more complex example is a CursorManagerSpecification created for a Source that has outputs. Suppose the application has an MdmMeasure that represents product units sold, and that measure has as inputs MdmPrimaryDimension objects that represent products, customers, times, and sales channels. The application gets Source objects for those measure and dimension objects, with the names units, productDim, customerDim, timeDim, and channelDim. The application then joins those Source objects to produce a Source, unitsSold, that has the values of the measure organized by the dimensions as outputs, as in the following:

 Source unitsSold = units.join(productDim)
                         .join(customerDim)
                         .join(timeDim)
                         .join(channelDim);

The application then calls the createCursorManagerSpecification method of the DataProvider and passes unitsSold to it. The CursorManagerSpecification returned by the method has the following CursorSpecification objects:

• A CompoundCursorSpecification for unitsSold, which is the root CursorSpecification for the CursorManagerSpecification.
• A base ValueCursorSpecification for the values of unitsSold.
• The first output, a ValueCursorSpecification for the values of channelDim.
• The second output, a ValueCursorSpecification for the values of timeDim.
• The third output, a ValueCursorSpecification for the values of customerDim.
• The fourth output, a ValueCursorSpecification for the values of productDim.

With the methods of a CursorSpecification, an application can specify that it wants information such as the extent of the Cursor, which is the total number of elements the Cursor contains, or the position in a parent Cursor at which a child Cursor starts or ends. Calculating the extent or the starting or ending positions can take a lot of time and computing resources, so an application should only set the CursorSpecification to do so when it needs the information.

An application can also set the default fetch size for a Cursor by calling the setDefaultFetchSize on the CursorSpecification for that Cursor. The fetch size is the number of elements that a Cursor retrieves during a single fetch from the data store. If the application sets the default fetch size on a CursorSpecification, it can then change the fetch size for the Cursor by calling the setFetchSize method of the Cursor itself.

With other methods of a CursorSpecification, an application can accept a CursorSpecificationVisitor or retrieve the Source for the CursorSpecification. The Source for a CursorSpecification is the Source that defines the data that the Cursor retrieves from the data store. For example, if an application calls getSource on the CompoundCursorSpecification for allSalesAmounts, from the example described above, then the Source returned by the method is allSalesAmounts. If the application calls getSource on the ValueCursorSpecification for timeDim, then the Source returned by the method is timeDim.

The OLAP API provides the following methods for gaining access to a CursorSpecification:

• CursorManagerSpecification.getRootCursorSpecification()
• CompoundCursorSpecification.getValueCursorSpecification()
• CompoundCursorSpecification.getOutputs()

Continuing the example from above, the following gets the CursorSpecification for timeDim. Because the ArrayList of outputs is zero-based, specifying the first element of the list gets the second output.

 CursorManagerSpecification cursorManagerSpecification =
                    dataProvider.createCursorManagerSpecification(unitsSold);
 CompoundCursorSpecification root =  (CompoundCursorSpecification)
                     cursorManagerSpecification.getRootCursorSpecification();
 CursorSpecification timeDimCursorSpecification = (CursorSpecification)
                                   (new ArrayList(root.getOutputs())).get(1);

getTransaction

public final Transaction getTransaction()

Gets the Transaction object for this CursorSpecification.

Returns:

The Transaction object for this CursorSpecification.

setTransaction

public final void setTransaction(Transaction transaction)

Specifies the Transaction object for this CursorSpecification.

Parameters:

transaction - The Transaction object for this CursorSpecification.

acceptVisitor

public abstract java.lang.Object acceptVisitor(CursorSpecificationVisitor visitor,
                                               java.lang.Object context)

Calls the visitCursorSpecification method of the specified CursorSpecificationVisitor and passes that method this CursorSpecification and the specified context Object.

Parameters:

visitor - A CursorSpecificationVisitor.

context - An Object.

Returns:

The Object returned by the visitCursorSpecification method.

getDefaultFetchSize

public final int getDefaultFetchSize()

Gets the fetch size set as the default for this CursorSpecification.

Returns:

The default fetch size for the CursorSpecification or Cursor.FETCH_SIZE_NOT_SPECIFIED if setting the default fetch size is not specified for this CursorSpecification.

getSource

public final Source getSource()

Gets the Source for this CursorSpecification.

Specified by:

getSource in interface CursorInfoSpecification

Returns:

The Source for this CursorSpecification.

isExtentCalculationSpecified

public final boolean isExtentCalculationSpecified()

Indicates whether the CursorSpecification is set to calculate the extent for the Cursor.

Returns:

true if the CursorSpecification is set to calculate the extent for the Cursor and false otherwise.

isParentEndCalculationSpecified

public final boolean isParentEndCalculationSpecified()

Indicates whether the CursorSpecification is set to calculate the ending position of the Cursor in the parent Cursor.

Specified by:

isParentEndCalculationSpecified in interface CursorInfoSpecification

Returns:

true if the CursorSpecification is set to calculate the ending position of the Cursor in the parent Cursor and false otherwise.

isParentStartCalculationSpecified

public final boolean isParentStartCalculationSpecified()

Indicates whether the CursorSpecification is set to calculate the starting position of the Cursor in the parent Cursor.

Specified by:

isParentStartCalculationSpecified in interface CursorInfoSpecification

Returns:

true if the CursorSpecification is set to calculate the starting position of the Cursor in the parent Cursor and false otherwise.

setDefaultFetchSize

public final void setDefaultFetchSize(int defaultFetchSize)
                               throws java.lang.IllegalArgumentException

Specifies a default fetch size for the Cursor. The default fetch size must be greater than zero. The fetch size can only be set at one level in the hierarchy of a parent Cursor and its children.

Parameters:

defaultFetchSize - The value to specify as the default fetch size.

setExtentCalculationSpecified

public final void setExtentCalculationSpecified(boolean b)

Specifies whether to calculate the extent of the Cursor. For a CompoundCursorSpecification, calling this method causes Oracle OLAP to calculate the extents of all of the descendents of the CompoundCursorSpecification.

Parameters:

b - true to calculate the extent and false otherwise.

setParentEndCalculationSpecified

public final void setParentEndCalculationSpecified(boolean b)

Specifies whether to calculate the ending position of the Cursor in the parent Cursor.

Specified by:

setParentEndCalculationSpecified in interface CursorInfoSpecification

Parameters:

b - true to calculate the ending position of the Cursor in the parent and false otherwise.

setParentStartCalculationSpecified

public final void setParentStartCalculationSpecified(boolean b)

Specifies whether to calculate the starting position of the Cursor in the parent Cursor.

Specified by:

setParentStartCalculationSpecified in interface CursorInfoSpecification

Parameters:

b - true to calculate the starting position of the Cursor in the parent and false otherwise.