com.businessobjects.customds.ui
Interface CustomDSExtension

All Known Implementing Classes:

AbstractCustomDSExtension

public interface CustomDSExtension

The CustomDSExtension interface is the Interactive Analysis Client / User Interface extension point. CDS Framework uses this interface to get plug-in specific user interface.

The plug-in provides the implementation of CustomDSComponent, which is used by the framework to get the plug-in specific user interface (a JComponent).

If the plug-in does not require any user inputs to access the data source, then no user interface plug-in is required for Interactive Analysis Client.

Since:

12.2

Method Summary

void	clean() Notifies the plug-in to do any clean-up activity.
CustomDSComponent	getCDSComponent(DataHolder dataHolder) Implementation of this method must return the instance that can provide the plug-in's user interface component.
javax.swing.ImageIcon	getDataProviderIcon() Implementation of this method must return the plug-in's data provider image icon, if any.
java.lang.String	getDataSourceDescription() Implementation of this method must return the description of the data source supported by the plug-in.
java.lang.String	getDisplayName() Implementation of this method must return the display name of the plug-in.
CDSExtensionDescriptor	getExtensionDescriptor() Invoked by the Framework after the instantiation of the plug-in through default constructor.
java.lang.String	getFileExtnDescription() Implementation of this method must return the description of file extensions of the supported files, if any.
java.lang.String	getHelpURL() Implementation of this method must return the plug-in Help URL.
java.lang.String	getHelpURL(java.lang.String context, java.lang.String errorMessage) Implementation of this method must return the plug-in Help URL.
javax.swing.ImageIcon	getImageIcon() Implementation of this method must return the plug-in's data source image icon, if any.
java.lang.String	getNewActionText() Implementation of this method must return the plug-in's new data provider action text, if any.
java.lang.String	getNewActionTooltip() Implementation of this method must return the plug-in's new data provider action tool-tip, if any.
javax.swing.ImageIcon	getNewDataProviderIcon() Implementation of this method must return the plug-in's data provider creation image icon, if any.
void	init(SessionInfo sessinfo) Invoked by the Framework after the call to CustomDSExtension.getExtensionDescriptor(), to enable the plug-in initialize itself for use by the Framework.
boolean	isExtensionHelpAvailable() Invoked by the Framework to check if the Framework must display plug-in specific help files or product help files.
void	setLocale(java.util.Locale loc) Implementation of this method must set or re-set the interface locale during this method call.

Method Detail

getExtensionDescriptor

CDSExtensionDescriptor getExtensionDescriptor()

Invoked by the Framework after the instantiation of the plug-in through default constructor. to know the plug-in details.

Please note that this method is called even before CustomDSExtension.init(SessionInfo) as it is used for plug-in identification.

Currently, the plug-in is instantiated during initial look-up only.

Since:

14.0

See Also:

CDSExtensionDescriptor

init

void init(SessionInfo sessinfo)
          throws CDSExtensionException

Invoked by the Framework after the call to CustomDSExtension.getExtensionDescriptor(), to enable the plug-in initialize itself for use by the Framework.

For information about the contents of the sessinfo parameter, see SessionInfo

Parameters:

sessinfo - The session information.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while processing the initial set of information.

Since:

12.2

See Also:

CDSExtensionException

setLocale

void setLocale(java.util.Locale loc)

Implementation of this method must set or re-set the interface locale during this method call.

The Framework invokes this method only if the default locale passed during CustomDSExtension.init(SessionInfo) method call is different from the current interface locale.

Parameters:

loc - The locale information.

Since:

12.2

getDisplayName

java.lang.String getDisplayName()

Implementation of this method must return the display name of the plug-in.

The plug-in must localize the display name based on the information sent during the init(SessionInfo) method call.

NOTE: The return value of this method is used only for display purpose and not for sending the plug-in information to the server for plug-in identification. The value returned by CDSExtensionBaseDescriptor.getDataSourceType() is used to identify the plug-in.

Returns:

The display name of the plug-in.

Since:

12.2

getFileExtnDescription

java.lang.String getFileExtnDescription()

Implementation of this method must return the description of file extensions of the supported files, if any.

The CDS framework uses this information to display the file chooser option in the file chooser dialog box.

This information is not used for plug-ins for which the resource type is "URL" or "NONE"(The value provided by the plug-in for call to CDSExtensionDescriptor.getDSResourceType()).

NOTE: If null or empty String is returned by this method call, the Framework forms the description with supported extensions.

Returns:

The file extension description for the plug-in.

Since:

12.2

getCDSComponent

CustomDSComponent getCDSComponent(DataHolder dataHolder)
                                  throws CDSExtensionException

Implementation of this method must return the instance that can provide the plug-in's user interface component.

The dataHolder parameter contains the details that enable the plug-in to build the user interface.

Framework assumes that no plug-in specific user interface is required if null is returned. So, plug-ins which does not require any user input for data provider creation, can customize plug-in specific data source / data provider display such as display name, icon and so on without providing any specific CustomDSComponent. Implementation of this method must return non-null value if the plug-in requires any user input for data provider creation.

This method is not called if return value of CDSExtensionDescriptor.requiresExtensionDialog() method is false.

Parameters:

dataHolder - The data holder.

Returns:

The CustomDSComponent object that provides plug-in's user interface component.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to provide the CustomDSComponent instance.

Since:

12.2

See Also:

CustomDSComponent, CDSExtensionException

getImageIcon

javax.swing.ImageIcon getImageIcon()
                                   throws CDSExtensionException

Implementation of this method must return the plug-in's data source image icon, if any.

The icon is used for display at different places to mark the association with data source. Examples of such places are the recently used data sources menu or panel, data view panel etc.

For a resource-based plug-in, if null is returned by the plug-in for this method call, the Framework attempts to provide a suitable icon. For a plug-in with resource-type as "FILE", it tries to get the icon from FileSystemView based on the supported file extensions of the plug-in. If it fails to get the icon from FileSystemView, a default icon is displayed. For a plug-in with resource-type as "URL", it provides a default icon.

Returns:

The data source image icon of the plug-in.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to provide the image icon.

Since:

12.2

See Also:

CDSExtensionException

getDataSourceDescription

java.lang.String getDataSourceDescription()
                                          throws CDSExtensionException

Implementation of this method must return the description of the data source supported by the plug-in.

The description is used for display at such places where it requires end user to pick a data source for creating a data provider.

If the returned value is null, framework uses the plug-in details to form the description.

Returns:

The description of the data source

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to get the data source description.

Since:

14.0

getDataProviderIcon

javax.swing.ImageIcon getDataProviderIcon()
                                          throws CDSExtensionException

Implementation of this method must return the plug-in's data provider image icon, if any.

The icon is used for associating existing data provider based on plug-in's data source.

For a resource-based plug-in, if null is returned by the plug-in for this method call, the Framework attempts to provide a suitable icon. For a plug-in with resource-type as "FILE", it tries to get the icon from FileSystemView based on the supported file extensions of the plug-in. If it fails to get the icon from FileSystemView, a default icon is displayed. For a plug-in with resource-type as "URL", it provides a default icon.

Returns:

The data provider image icon of the plug-in.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to provide the image icon.

Since:

14.0

getNewDataProviderIcon

javax.swing.ImageIcon getNewDataProviderIcon()
                                             throws CDSExtensionException

Implementation of this method must return the plug-in's data provider creation image icon, if any.

The icon is used for associating "New" data provider action in the data tool-box.

For a resource-based plug-in, if null is returned by the plug-in for this method call, the Framework attempts to provide a suitable icon. For a plug-in with resource-type as "FILE", it tries to get the icon from FileSystemView based on the supported file extensions of the plug-in. If it fails to get the icon from FileSystemView, a default icon is displayed. For a plug-in with resource-type as "URL", it provides a default icon.

Returns:

The data provider creation image icon of the plug-in.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to provide the image icon.

Since:

14.0

getNewActionText

java.lang.String getNewActionText()
                                  throws CDSExtensionException

Implementation of this method must return the plug-in's new data provider action text, if any.

The action text is used as a key to identify the command corresponding to add new data provider in the data tool-box.

If the returned value is null, framework uses the plug-in details to form the action text.

Returns:

The new data provider action text of the plug-in.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to get the action text for the new data provider.

Since:

14.0

getNewActionTooltip

java.lang.String getNewActionTooltip()
                                     throws CDSExtensionException

Implementation of this method must return the plug-in's new data provider action tool-tip, if any.

The returned value is used as tool-tip of the New data provider action in the data tool-box.

If the returned value is null, framework uses the plug-in details to form the action tool-tip.

Returns:

The new data provider action tool-tip of the plug-in.

Throws:

CDSExtensionException - if the plug-in encounters any Exception while trying to get the action tooltip for the new data provider.

Since:

14.0

isExtensionHelpAvailable

boolean isExtensionHelpAvailable()

Invoked by the Framework to check if the Framework must display plug-in specific help files or product help files.

Returns:

true if the plug-in needs to display its own help files; otherwise, false.

getHelpURL

java.lang.String getHelpURL()

Implementation of this method must return the plug-in Help URL. It can be an absolute path of the help file prefixed with "file:///" or a http URL.

If the CustomDSExtension.isExtensionHelpAvailable() method call returns false, then this method is not invoked by the framework.

If the return value of this method is null or empty, the product help files are displayed.

NOTE: The plug-in must provide localized help files based on the locale provided during CustomDSExtension.init(SessionInfo) method call.

Returns:

The help URL.

Since:

12.2

getHelpURL

java.lang.String getHelpURL(java.lang.String context,
                            java.lang.String errorMessage)

Implementation of this method must return the plug-in Help URL. It can be an absolute path of the help file prefixed with "file:///" or a http URL.

If the CustomDSExtension.isExtensionHelpAvailable() method call returns false, then this method is not invoked by the framework.

If the return value of this method is null or empty, the product help files are displayed.

NOTE: The plug-in must provide localized help files based on the locale provided during CustomDSExtension.init(SessionInfo) method call.

The context parameter value reflects the current user action. This value is similar to the one returned by call to com.businessobjects.customds.ui.CustomDSComponent.getActionTitle(). The value may be empty if an error occurs in user workflow. The value can be used in showing context sensitive help.

The errorMessage parameter value contains the error message, if any, when an error occurs in user workflow. It may be null for normal workflow or if error message is not available. The error code, if any, can be extracted from the error message to show help on specific errors.

Parameters:

context - The current context of user workflow

errorMessage - The error message, if any. May be null.

Returns:

The help URL.

Since:

14.0

clean

void clean()

Notifies the plug-in to do any clean-up activity.

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

Since:

12.2