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. Business Objects is an SAP company. All other product and service names mentioned are the trademarks of their respective companies. [. . . ] The following are the methods and its sample implementation of CDSExtensionDescriptor interface: 19 2010-11-05 Getting Started with Plug-in Development Methods Sample Implementation public String getName(){ return "Catalog XML"; } getName() getVersion() public String getVersion(){ return "1. 0"; } getDataSource Type() getDSDefaultLo cations() public String getDataSourceType(){ return "XML"; } public String[] getDSDefaultLocations(){ String[] dsDefaultLocations={"C:\\PersonalDPFiles\\Test. xml", "C:\\PersonalDP Files1\\Test1. xml"}; return dsDefaultLocations; } getDSFileExten sion() public String[] getDSFileExtension(){ String[] dsFileExtension={"*. xml"}; return dsFileExtension; } getDSResource Type() requiresExten sionDialog() public CDSExtensionResourceType getDSResourceType(){ return CDSExtensionResourceType. FILE; } public boolean requiresExtensionDialog(){ return true; } Note: The values returned by getName(), getVersion(), and getDataSourceType() methods must be same for DataProviderSource and User Interface plug-in implementation. The value of getData SourceType() should also be unique for each plug-in. In case of duplicates, both the plug-ins become unusable at runtime. 4. 4 CustomDataSource Interface Following are the CustomDataSource interface methods: · · getExtensionBaseDescriptor() - The Framework invokes this method after the instantiation of the plug-in through default constructor to retrieve the plug-in details. init (CustomDataSourceInfo customDataSourceInfo) - The Framework invokes this method after calling getExtensionBaseDescriptor() method. It is expected that the plug-in will initialize itself for use by the Framework and verify whether it can process the data source provided by the user. 20 2010-11-05 Getting Started with Plug-in Development Note: The verification of the validity or existence of the data source is not performed by the CDS Framework. 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. */ 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(); . . . . . . . . . . . . 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. [. . . ] You may encounter a similar problem if the value of the map entry is empty or null. · 35 2010-11-05 Utility Class The following is an example of the utility of the above-mentioned class: Map servicesMap = new HashMap(); Map portsMap1 = new HashMap(); Map portsMap2 = new HashMap(); Map methodsMap1 = new HashMap(); Map methodsMap2 = new HashMap(); servicesMap. put("QueryService", portsMap1); servicesMap. put("ReportEngineService", portsMap2); portsMap1. put("8080", methodsMap1); portsMap2. put("9090", methodsMap2); methodsMap1. put("Method1", "InputMethod"); methodsMap1. put("Method1. 2", "OutputMethod"); methodsMap2. put("Method2", new HashMap(). put(1, "$null$")); System. out. println("Map is : - "+servicesMap); ParamsSerializer paramSerialiser = new ParamsSerializer(); Map serialisedMap = paramSerializer. serialize(servicesMap); System. out. println("Serialised Map is : "+serialisedMap); Map deserialisedMap = paramSerialiser. deserialize(serialisedMap); System. out. println("De Serialized Map is : "+deserialisedMap); The output is as follows: Map is: - {ReportEngineService={9090={Method2=null}}, QueryService={8080={Method1. 2=OutputMethod, Method1=InputMethod}}} Serialized Map is : {QueryService#%pm*8080#%pm*Method1. 2#%pv*=OutputMethod, QueryService#%pm*8080#%pm*Method1#%pv*=InputMethod, ReportEngineService#%pm*9090#%pm*Method2#%pv*=#%pnl*} De Serialized Map is : {ReportEngineService={9090={Method2=null}}, QueryService={8080={Method1. 2=OutputMethod, Method1=InputMethod}}} 36 2010-11-05 Limitations of the CDS Framework Limitations of the CDS Framework The CDS Framework consumes any data source within the following limits: · Only data provider source extension point implementations that can provide data in a tabular format (Columns and Rows) are supported. · The CDS Framework does not provide direct/in-built capabilities to include authentication features for data source access. However, authentication feature can be achieved indirectly with data source parameters. · The CDS Framework does not support wizard-based access of data sources. [. . . ]