User manual BUSINESS OBJECTS XI 4.0 CUSTOM DATA PROVIDER PLUG-IN DEVELOPER GUIDE 2010-11-05

[. . . ] Custom Data Provider Plug-in Developer Guide SAP BusinessObjects XI 4. 0 2010-11-05 Copyright © 2010 SAP AG. All rights reserved. SAP, R/3, SAP NetWeaver, Duet, PartnerEdge, ByDesign, SAP Business ByDesign, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of Business Objects S. A. in the United States and in other countries. [. . . ] The plug-in is expected to throw an exception of type com. businessobjects. customds. exception. DataSourceException, if the source input is incorrect. The CustomDataSourceInfo() method parameter contains details such as source input, session ID, interface locale at the time when the call is made, and some information about the plug-in. public void init(CustomDataSourceInfo dataSourceInfo) throws DataSourceException{ CustomDataSourceInfo dsInfo = dataSourceInfo; String source = dsInfo. getSource(); boolean isURLSource = false; if(dsInfo. getDataSourceType()!= null) { isURLSource = dsInfo. getDataSourceType(). equalsIgnoreCase(URL_DSTYPE);//String to identify the URL dstype as configured in the configuration file } m_catalogParser = new CatalogXMLFileParser(source, isURLSource); try { Map catalogDetails = newHashMap(); catalogDetails. put("Books", "Book"); catalogDetails. put("Magazines", "Magazine"); m_catalogParser. parseStructure(catalogDetails); }catch (DataSourceException dse) { throw dse; } catch (Throwable t) { /* * if the cause is not known better to throw an error with "MINOR_GENERIC" as Minor code * also it is a good practice to put the Major code which can closely relate to the sequence flow */ throw new DataSourceException (t. getMessage(), ErrorCodes. MAJOR_GET_INFO_ERROR, ErrorCodes. MINOR_GENERIC); } } · getDSParameters (final Map currentDSParams) - The Framework invokes this method to obtain the data source parameters that must be in the form of key-value pairs. The key and value in a key-value pair must be non-null and non-empty java. lang. String objects. If the value in a key-value pair is empty, the Framework will delete it from the Map before storing it. public Map getDSParameters(final Map currentDSParams) throws DataSourceException{ boolean containCatalogDetails = false; boolean containColumnDetails = false; if (currentDSParams != null) { /* * This check is done to find out if it this call is for edit of the source or a new access call. * This kind of check can also be done by plug-ins which has incremental building of DS. * In both cases assumption is that the initial DS params are not removed */ Iterator currParamIter = currentDSParams. entrySet(). iterator(); while (currParamIter. hasNext ()) { Map. Entry currParamEntry = (Map. Entry) currParamIter. next (); String currParamKey = currParamEntry. getKey(). toString(); if (currParamKey. startsWith("catalog_xml_details. ")) containCatalogDetails = true; if(currParamKey. startsWith("catalog_xml_details_")) containColumnDetails = true; if(containCatalogDetails && containColumnDetails) break; } } if (containCatalogDetails && containColumnDetails) return currentDSParams; Map newParams = newHashMap(); Map catalogDetails = m_catalogParser. getCatalogDetails(); 21 2010-11-05 Getting Started with Plug-in Development Iterator paramIter = catalogDetails. entrySet(). iterator(); int index = 1; while(paramIter. hasNext ()) { Map. Entry paramEntry = (Map. Entry) paramIter. next(); String paramKey = paramEntry. getKey(). toString(); newParams. put("catalog_xml_details. " + index, paramKey); Vector paramValue = (Vector)paramEntry. getValue(); /* * If the implementation wants to throw an exception with a message that is not available in the pre-defined set of error codes, * it is expected to use the minor error code "MINOR_CUSTOM". However, it should be noted that in case of such (DataSourceException) * exception's with minor code mentioned as "MINOR_CUSTOM", the onus of passing the localized string is on the extension point implementation. * This localization can be achieved by using the locale passed by the framework during init method call. * This message is then shown to the user on the client side. */ if (paramValue == null) throw new DataSourceException ("Error While Parsing the Parameters", ErrorCodes. MAJOR_GET_INFO_ER ROR, ErrorCodes. MINOR_CUSTOM); Iterator colIter = paramValue. iterator(); int colIndex = 1; while (colIter. hasNext()) { Object colObj = colIter. next(); if( colObj == null) thrownew DataSourceException ("Unsupported XML", ErrorCodes. MAJOR_GET_INFO_ERROR, ErrorCodes. MINOR_CUSTOM); String colName = colObj. toString(); newParams. put("catalog_xml_details_"+paramKey+ ". "+ colIndex, colName); colIndex++; } if(colIndex == 1) throw new DataSourceException ("XML File doesn't contain structure information", ErrorCodes. MA JOR_GET_INFO_ERROR, ErrorCodes. MINOR_CUSTOM); index++; } return newParams; } · isDataSourceParamsComplete (final Map currentDSParams) - The Framework invokes this method to obtain information from the plug-in about its ability to access the data source and help build the Data Provider. When this call is made, the result can be any of the following: · The plug-in has received correct user input for the first set of data source parameters. However, the plug-in requires more user input for other data source parameter sets. · Users attempted to perform the next set of operations (such as obtaining the details of selected objects and sample data) without providing adequate information. · Input provided by the user is adequate for the plug-in to access the data source and help build the Data Provider. In the first two cases, plug-in returns false for the isDataSourceParamsComplete (final Map currentDSParams) method. This method returns true for the third case. public boolean isDataSourceParamsComplete (finalMap currentDSParams) throws DataSourceException { boolean hasSelectedCols = false; Object obj = currentDSParams. get(CDS_XML_SELECTED_COLS); if(obj != null) { String strSelCols = obj. toString(); if(!(strSelCols. equals(""))) hasSelectedCols = true; } return (currentDSParams. containsKey(CDS_XML_SELECTED_DETAIL) &&hasSelectedCols); } · getColumnsInfo (final Map currentDSParams) - The Framework invokes this method to obtain the details of object(s) (column(s)) that are used to build the interactive analysis data provider. 22 2010-11-05 Getting Started with Plug-in Development Following is a sample code snippet: public ColumnsInfo getColumnsInfo (final Map currentDSParams) throws DataSourceException { ColumnsInfo columnsInfo = new ColumnsInfo(); . . . . . . . . . . . . String colName = obj. toString(); Integer colType = . . . ; . . . . . . . . . . . . columnsInfo. addColumn(new ColumnSpec(colName, colType. intValue())); . . . . . . . . . . . . return columnsInfo; } · getChunkSize () - The Framework invokes this method to obtain the size of each chunk provided by the plug-in's CustomDataProvider implementation. public int getChunkSize () throws DataSourceException { return DEFAULT_CHUNK_SIZE; } Where publicstaticfinalint DEFAULT_CHUNK_SIZE = 100; · getCustomDataProvider (ColumnSpec[] columnSpecs) - The Framework invokes this method to obtain the implementation for the plug-in's Data Provider. public CustomDataProvider getCustomDataProvider(ColumnSpec[] columnSpecs) throws DataSourceException { return new XMLCatalogDataProvider(m_selCatalogItem, columnSpecs); } · clean () - The Framework invokes this method to allow the plug-in to perform any clean-up activity. AbstractCustomDataSource is the abstract implementation for the CustomDataSource interface. 4. 5 CustomDataProvider Interface Following are the CustomDataProvider Interface methods: · openIterator (final IteratorInfo iteratorInfo, ColumnSpec[] columnSpecs) - The Framework invokes this method to provide the details of interactive analysis Data Provider objects/columns and the data iterator ID. It is expected that the plug-in will provide the required information for the IteratorInfo object. The following points must be noted while implementing this method: The Framework can take any of the following paths to obtain the data: · Before each call to the getNextChunk() method, the Framework invokes the hasNextChunk() method to check whether the next data chunk is available. · The Framework continues to call the getNextChunk() method based on the total number of rows available for the Data Provider, as specified by the plug-in. [. . . ] However, you can simulate a wizard-like workflow (without full-fledged capabilities of a wizard) by implementing incremental access to data sources. · The CDS Framework does not support automated generation of plug-ins for data sources. However, a few samples are provided to demonstrate implementations of various extensions. 37 2010-11-05 Limitations of the CDS Framework 38 2010-11-05 Best Practices Best Practices Following are some best practices that you can consider while developing a plug-in: · Though there are no technical limitations, allowing for future enhancements, it is recommended that User Interface plug-in classes/interfaces must not refer to any classes/interfaces contained in DPS plug-in binary (jar) or vice versa. It is recommended that the DPS plug-in implementation and the User Interface plug-in implementation are packaged in two separate . jar files. · 39 2010-11-05 Best Practices 40 2010-11-05 More Information More Information Information Resource Location SAP BusinessObjects product information http://www. sap. com Navigate to http://help. sap. com/businessobjects and on the "SAP BusinessObjects Overview" side panel click All Products. [. . . ]