com.businessobjects.customds
Interface CustomDataSource

All Known Implementing Classes:

AbstractCustomDataSource

public interface CustomDataSource

The CustomDataSource interface is the Interactive Analysis Server/Processing layer extension point of the Custom Data Source Framework(CDS Framework). CDS Framework uses this interface to access plug-in specific data source and create the data provider (query formed out of selected objects).

The plug-in (extension point implementation of the Framework) provides the necessary data source parameters to access the data source (during CustomDataSource.getDSParameters(Map) method invocation). These parameters are sent to the User Interface plug-in implementation for building the user interface. After user inputs, the Framework verifies whether the plug-in is capable of accessing the data source for the data provider through CustomDataSource.isDataSourceParamsComplete(Map) method invocation. After the plug-in receives all the required user inputs, the Framework requests the plug-in to provide the details required to create the data provider. The details include the name and ObjectType of columns, which forms the objects for the data provider.

After the objects are identified to build the data provider, the Framework requests the implementation of the plug-in to retrieve data.

Exceptions thrown before the plug-in receives all the input to access the data source makes the status of the data source "invalid". Hence, some of the error messages that need to be shown to the user for any invalid input must be passed to the client in the form of data source parameter and not as exceptions. This also means that calls to method isDataSourceParamsComplete(Map) must return false. If true is returned, then method getDSParameters(Map) is not called further by the framework. Hence, errors caused by invalid user input that are identified later must be propagated to the user in the form of exceptions. To correct the input, the user must edit the data source parameters.

Since:

12.2

Method Summary

void	clean() Notifies the plug-in to perform required clean-up activities.
int	getChunkSize() Implementation of this method must return the size of each Chunk that must be returned by the plug-in's CustomDataProvider implementation.
ColumnsInfo	getColumnsInfo(java.util.Map currentDSParams) Implementation of this method must return the details of the object(s) (column(s)) used to build the data provider.
CustomDataProvider	getCustomDataProvider(ColumnSpec[] columnSpecs) Implementation of this method must return an object for the data provider of the plug-in.
java.util.Map	getDSParameters(java.util.Map currentDSParams) Implementation of this method must return additional set of data source parameters, if any, in the form of key (String(non-null))- value (String) pairs.
CDSExtensionBaseDescriptor	getExtensionBaseDescriptor() Invoked by the Framework after the instantiation of the plug-in through default constructor to know the plug-in details.
void	init(CustomDataSourceInfo customDataSourceInfo) Invoked by the Framework after the call to CustomDataSource.getExtensionBaseDescriptor(), to enable the plug-in to initialize itself.
boolean	isDataSourceParamsComplete(java.util.Map currentDSParams) Implementation of this method must return true if the plug-in is ready to access the data source with the given set of user inputs.

Method Detail

getExtensionBaseDescriptor

CDSExtensionBaseDescriptor getExtensionBaseDescriptor()

Invoked by the Framework after the instantiation of the plug-in through default constructor to know the plug-in details. Note that this method is called even before CustomDataSource.init(CustomDataSourceInfo) as it is used for plug-in identification.

The plug-in is instantiated during look-up and later each time a request is made to access a new data source. However, this method is expected to return similar information each time, otherwise, an error may occur.

Since:

14.0

See Also:

CDSExtensionBaseDescriptor

init

void init(CustomDataSourceInfo customDataSourceInfo)
          throws DataSourceException

Invoked by the Framework after the call to CustomDataSource.getExtensionBaseDescriptor(), to enable the plug-in to initialize itself.

For more information, see CustomDataSourceInfo.

Parameters:

customDataSourceInfo - The CustomDataSourceInfo object contains basic information required to access the data source and to identify the details of the plug-in.

Throws:

DataSourceException - if the plug-in encounters any Exception while processing the initial set of information. Plug-in must mask handled exceptions as DataSourceException by using one of its constructors. Most common DataSourceException can be either missing or invalid source (ErrorCodes.MINOR_FILE_MISSING or ErrorCodes.MINOR_INVALID_FILE_PATH).

Since:

12.2

See Also:

CustomDataSourceInfo, DataSourceException, ErrorCodes

getDSParameters

java.util.Map getDSParameters(java.util.Map currentDSParams)
                              throws DataSourceException

Implementation of this method must return additional set of data source parameters, if any, in the form of key (String(non-null))- value (String) pairs.

The data source parameters are sent to the Interactive Analysis client to generate the user interface to obtain the user inputs required by the plug-in to access the data source.

NOTE:

The Map elements must only be a key-value pair, i.e. key (String(non-null))- value (String(non-null)). If a value other than non-empty string is returned, then the value is converted to a String. If the key is an empty string, it is ignored and no error messages are displayed.

Parameters:

currentDSParams - The current data source parameters.

Returns:

Map containing additional set of data source parameters. It can be null if the plug-in does not require any further parameters to be sent to the client.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to build the additional set of information required to access the data source. Plug-in must mask handled exceptions as DataSourceException by using one of its types.

Since:

12.2

See Also:

DataSourceException

isDataSourceParamsComplete

boolean isDataSourceParamsComplete(java.util.Map currentDSParams)
                                   throws DataSourceException

Implementation of this method must return true if the plug-in is ready to access the data source with the given set of user inputs.

There can be three possibilities during this method call:

• The plug-in has obtained user inputs for the first set of data source parameters but also has additional set of data source parameters for which it requires user inputs.

• User provided invalid inputs and attempted to perform the next set of operations (trying to get details of selected object(s), sample data etc.)

In both of the above cases, the plug-in is expected to return false.

• The inputs from the user are sufficient to access the data source. In this case, the plug-in is expected to return true.

Parameters:

currentDSParams - The current data source parameters

Returns:

true, if no more input is required from the user to access the data source; otherwise false.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to verify if the user input is complete. The plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

Since:

12.2

See Also:

DataSourceException

getColumnsInfo

ColumnsInfo getColumnsInfo(java.util.Map currentDSParams)
                           throws DataSourceException

Implementation of this method must return the details of the object(s) (column(s)) used to build the data provider.

Number of objects(Columns)/ColumnSpec depends on the user selection, if the plug-in has sent parameters to obtain the user input.

If ColumnsInfo object is null or does not contain any ColumnSpecs, then the Framework throws a DataSourceException.

For adding ColumnSpec to ColumnsInfo object, use the ColumnsInfo.addColumn(ColumnSpec) method. For information about ColumnSpec creation, see ColumnSpec.

Parameters:

currentDSParams - The current data source parameters containing the initial state of data source parameters (user selection).

Returns:

The ColumnsInfo object containing the collection of ColumnSpec which is part of the data provider.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to get the details of data provider objects. Plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

Since:

12.2

See Also:

ColumnsInfo, ColumnSpec, DataSourceException

getCustomDataProvider

CustomDataProvider getCustomDataProvider(ColumnSpec[] columnSpecs)
                                         throws DataSourceException

Implementation of this method must return an object for the data provider of the plug-in.

The returned object is used to fetch data for data provider of Interactive Analysis.

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) to this method. 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".

Also, 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.

Parameters:

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

Returns:

CustomDataProvider, the data provider implementation object.

Throws:

DataSourceException - if the plug-in encounters any Exception while trying to get data provider information. Plug-in must mask handled exceptions as DataSourceException by using one of its constructors.

Since:

12.2

See Also:

ColumnSpec, DataSourceException

getChunkSize

int getChunkSize()
                 throws DataSourceException

Implementation of this method must return the size of each Chunk that must be returned by the plug-in's CustomDataProvider implementation.

The CustomDataProvider.setChunkSize(int, int) method is used to set the chunk size of the data provider.

Returns:

The chunk size for the CustomDataProvider implementation.

Throws:

DataSourceException - If the plug-in encounters any Exception while trying to get the size of chunk.

Since:

12.2

clean

void clean()

Notifies the plug-in to perform required clean-up activities.

This call marks the end of life-cycle of the plug-in.

Since:

12.2