com.businessobjects.customds
Interface CustomDataProvider

All Known Implementing Classes:

AbstractCustomDataProvider

public interface CustomDataProvider

The CustomDataProvider interface is used to retrieve data from the plug-in (extension of CDS Framework) for the data provider.

After the objects are identified to build the data provider through the CustomDataSource implementation, the CDS Framework requests for data by using this interface.

Since:

12.2

Method Summary

void	cancel(int iIterId) Notifies the plug-in to cancel any operation on the Data Iterator identified by the ID sent while calling the openIterator(IteratorInfo, ColumnSpec[]) method.
void	closeIterator(int iIterId) Notifies the plug-in that the Data Iterator identified by the ID sent while calling openIterator(IteratorInfo, ColumnSpec[]) method is closed.
Chunk	getNextChunk(int iIterId, ColumnSpec[] columnSpecs) Implementation of this method must return next Chunk of data.
boolean	hasNextChunk(int iIterId) Checks if the plug-in has more chunks to return.
void	openIterator(IteratorInfo iteratorInfo, ColumnSpec[] columnSpecs) Invoked by the Framework to provide and retrieve some of the details of IteratorInfo.
void	setChunkSize(int iIterId, int chunkSize) Invoked by the Framework to enable the plug-in set the Chunk size.

Method Detail

openIterator

void openIterator(IteratorInfo iteratorInfo,
                  ColumnSpec[] columnSpecs)
                  throws DataSourceException

Invoked by the Framework to provide and retrieve some of the details of IteratorInfo. This method is called by the Framework before retrieving the data from the plug-in for each Data Iterator.

The IteratorInfo object is created by the Framework with a unique ID and sent to the plug-in to initialize other details such as Row Count and so on.

The Iterator ID can be retrieved from IteratorInfo.getIteratorId().

The ColumnSpec(s) sent as parameter to this method contains information that is similar to the information returned by the plug-in when a call to getColumnsInfo(Map) is performed. However, if a user changes the data-type of the data provider objects, the information is accordingly modified in the ColumnSpec(s). Hence, the ColumnSpec(s) sent as parameter to this method need not be similar to the one returned by the plug-in for data-types.

Parameters:

iteratorInfo - Contains the Iterator ID.

columnSpecs - An array of ColumnSpec containing the information about the objects used for data provider creation.

Throws:

DataSourceException - if the plug-in encounters any Exception while preparing itself to provide data. Plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

See Also:

IteratorInfo, DataSourceException

setChunkSize

void setChunkSize(int iIterId,
                  int chunkSize)
                  throws DataSourceException

Invoked by the Framework to enable the plug-in set the Chunk size.

The plug-in must set the default size for the Chunk, which will be retrieved by the Framework during call of CustomDataProvider.getNextChunk(int, ColumnSpec[]) method for the Data Iterator. When the Framework calls the setChunkSize method, the plug-in must set its maximum chunk size to the specified value by the framework.

Parameters:

iIterId - The Data Iterator ID

chunkSize - The chunk size set by the Framework.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to set the chunk size. Plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

See Also:

Chunk, IteratorInfo

getNextChunk

Chunk getNextChunk(int iIterId,
                   ColumnSpec[] columnSpecs)
                   throws DataSourceException

Implementation of this method must return next Chunk of data.

The ColumnSpec(s) sent as parameter to this method contains information that is similar to the information returned by the plug-in when a call to getColumnsInfo(Map) is performed. However, if a user changes the data-type of the data provider objects, the information is accordingly modified in the ColumnSpec(s). Hence, the ColumnSpec(s) sent as parameter to this method need not be similar to the one returned by the plug-in for data-types.

Therefore, the plug-ins must return appropriate data based on the data-type provided for methods applicable to the data provider. The plug-in can throw an exception if it does not support this conversion or return null/default values for which it cannot retrieve data based on the user selected data-type. For example, consider an object named as "Column1", and the data-type/column-type is "String" and values contained in the database are "Test" and "1". If user changes the data-type to "Number", then the plug-in may choose to either throw an exception when it receives a request for data or it may choose to return null/""/0 for value "Test" and 1 for value "1".

The plug-in must implement its own logic if more than one column has the same name, and if the data-type is changed for one and not for other or any such cases of change in the data-type.

Framework throws DataSourceException, if null is returned or if the ColumnSpecs of the Chunk and the one sent as parameter do not match.

Parameters:

iIterId - The Data Iterator ID sent while calling CustomDataProvider.openIterator(IteratorInfo, ColumnSpec[]).

columnSpecs - An array of ColumnSpec containing the information about the objects used for data provider creation by calling CustomDataSource.getColumnsInfo(Map).

Returns:

The chunk of data.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to retrieve the next chunk of data. The plug-in must mask handled exceptions as DataSourceException by using one of its constructors. This exception is also thrown if getNextChunk() method returns null or if the ColumnSpec(s) of the Chunk and the one sent as parameter do not match.

See Also:

Chunk, IteratorInfo

hasNextChunk

boolean hasNextChunk(int iIterId)
                     throws DataSourceException

Checks if the plug-in has more chunks to return.

Parameters:

iIterId - The Data Iterator ID sent while calling the openIterator method.

Returns:

true, if the plug-in still has chunks for the Data Iterator; otherwise false.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to get the next set of data chunk(s) to return. The plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

See Also:

Chunk, IteratorInfo

closeIterator

void closeIterator(int iIterId)

Notifies the plug-in that the Data Iterator identified by the ID sent while calling openIterator(IteratorInfo, ColumnSpec[]) method is closed. If required, a new Data Iterator is created by the Framework by calling the CustomDataProvider.openIterator(IteratorInfo, ColumnSpec[]) method.

Parameters:

iIterId - The Data Iterator ID

See Also:

IteratorInfo

cancel

void cancel(int iIterId)

Notifies the plug-in to cancel any operation on the Data Iterator identified by the ID sent while calling the openIterator(IteratorInfo, ColumnSpec[]) method. This is called when user tries to cancel refresh operation.

Parameters:

iIterId - The Data Iterator ID

See Also:

IteratorInfo