com.businessobjects.rebean.wi
Interface DataProviders

public interface DataProviders

The DataProviders interface defines a collection of data providers.

See Also:

DataProvider, DocumentInstance.getDataProviders()

Method Summary

void	changeDataSource(java.lang.String oldDataSourceID, java.lang.String newDataSourceID, boolean applyMapping) Deprecated. Use DataProviders.changeUniverse(String, String, boolean).
void	changeUniverse(java.lang.String olduniverseid, java.lang.String newuniverseid, boolean applyMapping) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	clearContexts() Warning:This interface is no longer functional from the SAP BusinessObjects XI 4.0 release onwards.
DataProvider	createDP(java.lang.String dataSourceID, int index) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	deleteDP(int index) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	deleteDP(java.lang.String name) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
DataProvider	duplicate(int index) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
Query	findQueryFromConditionID(java.lang.String conditionID) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	generateQueries() Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
boolean	getCanChangeDataSource() Deprecated. Use DataProviders.getCanChangeUniverse().
boolean	getCanChangeUniverse() Checks if this document supports replacing one universe by another.
ChangeDataSourceMapping	getChangeDataSourceMapping() Deprecated. Use DataProviders.getChangeUniverseMapping() instead of this call.
ChangeUniverseMapping	getChangeUniverseMapping() Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
int	getCount() Gets the number of data providers in the collection.
DataProvider	getItem(int index) Returns the data provider at the specified position in the list.
DataProvider	getItem(java.lang.String name) Returns a data provider by name.
CharacterView	getResultAsXML() Get the all the DPResults as XML output
CharacterView	getView(OutputFormatType outputFormat) Retrieves aggregated data providers data in CSV (Comma Separated Values) or Xml format.
void	move(int from, int to) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
boolean	mustFillChangeDataSourceMapping() Deprecated. Use DataProviders.mustFillChangeUniverseMapping().
boolean	mustFillChangeUniverseMapping() Checks if any object mapping must be validated after calling DataProviders.changeUniverse(String, String, boolean).
void	purgeAll() Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	purgeAll(boolean purgePromptValues) Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.
void	runQueries() Updates all modifications made in any query in any data provider, and refreshes all data in each data provider.
void	runQueries(boolean refreshAllDPWithRights) Updates all modifications made in any query in any data provider, and refreshes all data in each data provider.
void	setChangeDataSourceMapping() Deprecated. Use DataProviders.getChangeUniverseMapping() instead of this call.
void	setChangeUniverseMapping() Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Method Detail

getCount

int getCount()

Gets the number of data providers in the collection.

Returns:

the number of data providers

getItem

DataProvider getItem(int index)

Returns the data provider at the specified position in the list.

Parameters:

index - the index of the data provider to return (0 based)

Returns:

the data provider at the specified index

Throws:

java.lang.ArrayIndexOutOfBoundsException - if index is out of range (index < 0 || index >= getCount())

getItem

DataProvider getItem(java.lang.String name)

Returns a data provider by name.

Parameters:

name - name of the data provider to return

Returns:

a data provider, or null when no data provider in this collection has a name corresponding to name

getResultAsXML

CharacterView getResultAsXML()

Get the all the DPResults as XML output

Returns:

characterView of the DPResults

See Also:

for full description of the Data Provider DTD

createDP

DataProvider createDP(java.lang.String dataSourceID,
                      int index)
                      throws REException

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Creates a new data provider.

Parameters:

dataSourceID - the ID of the universe the new data provider should be based on

index - the index of the new data provider (index < 0 means "at the end")

Returns:

the new data provider

Throws:

REException

java.lang.ArrayIndexOutOfBoundsException - when index > getCount()

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

Since:

6.5.0

duplicate

DataProvider duplicate(int index)
                       throws REException

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Duplicates an existing data provider. The new data provider is added at the end of the list.

Parameters:

index - the index of the data provider to copy

Returns:

the new data provider

Throws:

REException

java.lang.ArrayIndexOutOfBoundsException - when index < 0 or index >= getCount()

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

Since:

6.5.0

move

void move(int from,
          int to)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Moves a data provider to another position. The data provider currently at index from will be moved so that after calling this function, its index will be to.

Does nothing when from == to.

Parameters:

from - the index of the data provider to move

to - the new index

Throws:

java.lang.ArrayIndexOutOfBoundsException - when from or to are invalid

REException

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

Since:

6.5.0

deleteDP

void deleteDP(int index)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Deletes the data provider at index index.

Parameters:

index - the index of the data provider to delete

Throws:

java.lang.ArrayIndexOutOfBoundsException - when index is invalid

REException - when a server error occurred or when the data provider at index is the last one.

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

Since:

6.5.0

deleteDP

void deleteDP(java.lang.String name)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Deletes the data provider with name name. When no data provider has the specified name, nothing happens.

Parameters:

name - the name of the data provider to delete

Throws:

REException - when a server error occurred or the data provider with name name is the last one

Since:

6.5.0

runQueries

void runQueries()

Updates all modifications made in any query in any data provider, and refreshes all data in each data provider.

Throws:

REException

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

Since:

6.5.0

See Also:

DataProvider.runQuery()

runQueries

void runQueries(boolean refreshAllDPWithRights)

Updates all modifications made in any query in any data provider, and refreshes all data in each data provider. With the extra parameter added we are giving instructions to server as refresh only the DP which has rights for the specific user

Parameters:

refreshAllDPWithRights - - true - On true, it will allow to refresh the document with only allowed MDP - false - On false, it will not perform any action, in case if it is accessed from SDK as false, it will try to refresh only the one which are allowed

Throws:

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines#getService(int type) for more information.

REException - is an general execption which will be thrown at any failure in refresh action

Since:

12.2

See Also:

this is method resemblence is there completely, execusively that parameter check, DataProvider.runQuery()

generateQueries

void generateQueries()
                     throws REException

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Updates the query definition for any modified queries in this list of data providers.

Throws:

REException

NotImplementedException - if ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance was opened to run Desktop Intelligence documents. See ReportEngines.getService(com.businessobjects.rebean.wi.ReportEngines.ReportEngineType) for more information.

Since:

6.5.0

See Also:

DataProvider.generateQuery()

purgeAll

void purgeAll()

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Purges all data providers. Once a data provider has been purged, it no longer contains any data. In other words, after calling this method, the document will not contain data anymore.

Calling this method has the same effect as calling purgeAll(false);

Throws:

NotImplementedException - Thrown when ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance used to open this DataProvider was opened to run Desktop Intelligence documents. See ReportEngines.getService(com.businessobjects.rebean.wi.ReportEngines.ReportEngineType) for more information.

Since:

11.7

purgeAll

void purgeAll(boolean purgePromptValues)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Purges all data providers. Once a data provider has been purged, it no longer contains any data. In other words, after calling this method, the document will not contain data anymore.

Parameters:

purgePromptValues - if true, prompt values used during the last refresh will be reset, too.

Throws:

NotImplementedException - Thrown when ReportEngine.getCanEditDocument() returns false. That is to say, the ReportEngine instance used to open this DataProvider was opened to run Desktop Intelligence documents. See ReportEngines.getService(com.businessobjects.rebean.wi.ReportEngines.ReportEngineType) for more information.

Since:

11.7

findQueryFromConditionID

Query findQueryFromConditionID(java.lang.String conditionID)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Returns the query from one of its query condition identifier. The query condition identifier FilterConditionNode.getID() is unique for all data providers.

Parameters:

conditionID -

Returns:

the query contains the condition

Since:

11.5

getCanChangeDataSource

@Deprecated
boolean getCanChangeDataSource()

Deprecated. Use DataProviders.getCanChangeUniverse().

Checks if this document supports replacing one data source by another.

Returns:

true when this document type supports changing data source.

Since:

11.5

changeDataSource

@Deprecated
void changeDataSource(java.lang.String oldDataSourceID,
                                 java.lang.String newDataSourceID,
                                 boolean applyMapping)

Deprecated. Use DataProviders.changeUniverse(String, String, boolean).

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Replaces all occurrences of a data source with another one. After calling this method with applyMapping == true, the default mapping needs to be validated (so DataProviders.mustFillChangeDataSourceMapping() will return true). After that, possibly DocumentInstance.getMustFillContexts() will return true, indicating at least a context must be resolved.

Once this method has been called, it is not possible to cancel the operation; the mapping and contexts must be set in order for the document to be ready for use.

After completing the full workflow, all occurrences of the data source identified by oldDataSourceID will have been replaced by the data source identified by newDataSourceID. This includes all data providers, the document dictionary including any variables and synchronized objects, and all reports.

A typical workflow of changing the data source is:

 dataProviders.changeDataSource(oldID, newID, true);
 if (dataProviders.mustFillChangeDataSourceMapping()) {
     // This will always be the case.
     ChangeDataSourceMapping mapping = dataProviders
             .getChangeDataSourceMapping();
 
     // Display the mapping and change it when necessary...
 
     // Validate the mapping.
     dataProviders.setChangeDataSourceMapping();
 
     if (document.getMustFillContexts()) {
         Contexts contexts = document.getContexts();
 
         // Answer the contexts...
 
         document.setContexts();
     }
 }
 

When applyMapping == false, this method simply changes the ID in the references to the old data source into the new one. This may leave the document in a state where all queries based on the old data source contain invalid objects. Calling this method with applyMapping == false is strongly discouraged for most cases. It can however be useful when the old data source is no longer available and the caller is absolutely certain that the new data source is a valid replacement. This means that all object IDs must be equal to the old ones and that all objects are of the same type and qualification.

Parameters:

oldDataSourceID - The ID of the data source to replace.

newDataSourceID - The ID of the new data source.

applyMapping - When true, DataProviders.mustFillChangeDataSourceMapping() will return true after calling this method and the mapping must be set. When false, no mapping will be applied; only the universe ID will be changed. This means that queries based on the old data source may become invalid.

Throws:

java.lang.NullPointerException - Thrown when either oldDataSourceID or newDataSourceID are null.

java.lang.IllegalArgumentException - Thrown when either oldDataSourceID or newDataSourceID are not IDs of valid data sources.

QueryException - Thrown when applyMapping == true and at least one impacted query is empty. When applying a mapping, all impacted source queries must have at least one object.

REException - Thrown when there was a problem accessing the old or the new data source (for example, when the current user does not have sufficient rights to access both data sources).

Since:

11.5

See Also:

DataSource.getID()

mustFillChangeDataSourceMapping

@Deprecated
boolean mustFillChangeDataSourceMapping()

Deprecated. Use DataProviders.mustFillChangeUniverseMapping().

Checks if the object mapping must be validated after calling DataProviders.changeDataSource(String, String, boolean).

Returns:

true if the mapping must be validated.

Since:

11.5

getChangeDataSourceMapping

@Deprecated
ChangeDataSourceMapping getChangeDataSourceMapping()

Deprecated. Use DataProviders.getChangeUniverseMapping() instead of this call.

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Returns the data source mapping, after a call to DataProviders.changeDataSource(String, String, boolean) with the applyMapping argument set to true.

Returns:

The mapping describing how each old object will be replaced after the data source change, or null when DataProviders.mustFillChangeDataSourceMapping() returns false.

Since:

11.5

setChangeDataSourceMapping

@Deprecated
void setChangeDataSourceMapping()

Deprecated. Use DataProviders.getChangeUniverseMapping() instead of this call.

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Validates the current data source mapping, when changing a data source. After calling this method, all impacted queries will be changed according to the current object mapping. I this changes a query (this will be the case unless all objects and their IDs remain identical), then the document will be purged.

After calling this method, one or more contexts may have to be filled. Always check this by calling DocumentInstance.getMustFillContexts().

Internally, this method updates all impacted queries and calls DataProviders.generateQueries(). Once any contexts have been filled, the new report dictionary is used to replace all impacted objects in any variables and the document structure.

Throws:

QueryException - Thrown when at least one of the impacted queries would be empty after applying the mapping.

Since:

11.5

See Also:

DataProviders.changeDataSource(String, String, boolean), DataProviders.getChangeDataSourceMapping()

getCanChangeUniverse

boolean getCanChangeUniverse()

Checks if this document supports replacing one universe by another.

Returns:

true when this document type supports changing universe.

Since:

12.5

mustFillChangeUniverseMapping

boolean mustFillChangeUniverseMapping()

Checks if any object mapping must be validated after calling DataProviders.changeUniverse(String, String, boolean).

Returns:

true if the mapping must be validated.

Since:

12.5

changeUniverse

void changeUniverse(java.lang.String olduniverseid,
                    java.lang.String newuniverseid,
                    boolean applyMapping)

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Changes old universe by the new one in the document. It means that all occurrences of a data source object will be replaced by another one of new universe. When applyMapping is true, this call provides a ChangeUniverseMapping containing all old data source object to be replaced with a possible new data source object default mapping. This mapping needs to be validated (so DataProviders.mustFillChangeUniverseMapping() will return true). After that, possibly DocumentInstance.getMustFillContexts() will return true, indicating at least a context must be resolved.

After DataProviders.setChangeUniverseMapping() call and resolution of contexts, all occurrences of the data source identified by oldDataSourceID will have been replaced by the data source identified by newDataSourceID. This includes all data providers, the document dictionary including any variables and synchronized objects, and all reports.

A full workflow must be completed by DocumentInstance.applyFormat() and DocumentInstance.refresh().

 dataProviders.changeUniverse(oldID, newID, true);
 if (dataProviders.mustFillChangeUniverseMapping()) {
     // This will always be the case.
     ChangeUniverseMapping mapping = dataProviders
             .getChangeUniverseMapping();
 
     // Display the mapping and change it when necessary...
 
     // Validate the mapping.
     dataProviders.setChangeUniverseMapping();
 
     if (document.getMustFillContexts()) {
         Contexts contexts = document.getContexts();
         // Answer the contexts...
         document.setContexts();
     }
     document.applyFormat();
     document.refresh();
 }
 

Parameters:

olduniverseid - old universe id to be replaced DataSource.getUniverseID()

newuniverseid - new universe id DataSource.getUniverseID()

applyMapping - When true, DataProviders.mustFillChangeUniverseMapping() will return true after calling this method and the mapping must be set. When false, no mapping will be applied; only the universe ID will be changed. This means that queries based on the old universe may become invalid.

Since:

12.5

getChangeUniverseMapping

ChangeUniverseMapping getChangeUniverseMapping()

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Returns a universe mapping containing all instances of data source mapping consequently a call to DataProviders.changeUniverse(String, String, boolean) with the applyMapping argument set to true.

Returns:

The mapping describing how each old object will be replaced after the data source change, or null when DataProviders.mustFillChangeDataSourceMapping() returns false.

Since:

12.5

setChangeUniverseMapping

void setChangeUniverseMapping()

Warning: This method is no longer functional from the SAP BusinessObjects 4.0 release onwards.

Validates the current universe mapping, when changing a universe. After calling this method, all impacted queries will be changed according to the current object mapping. And all report expressions of document will be updated using current object mapping, then the document will be purged.

After calling this method, one or more contexts may have to be filled. Always check this by calling DocumentInstance.getMustFillContexts().

Internally, this method updates all impacted queries and calls DataProviders.generateQueries(). Once any contexts have been filled, the new report dictionary is used to replace all impacted objects in any variables and the document structure.

In order to update the document with updated report expressions and new universe data, DocumentInstance.applyFormat() and DocumentInstance.refresh() should be called.

Throws:

QueryException - Thrown when at least one of the impacted queries would be empty after applying the mapping.

Since:

12.5

See Also:

DataProviders.changeUniverse(String, String, boolean), DataProviders.getChangeUniverseMapping()

getView

CharacterView getView(OutputFormatType outputFormat)

Retrieves aggregated data providers data in CSV (Comma Separated Values) or Xml format.

Parameters:

outputFormat - The output format (must be CSV or XML)

Returns:

an interface from which data can be retrieved in the required format.

Throws:

java.lang.Exception - outputFormat is not a valid member from the OutputFormatType or is not supported.

Since:

11.5

clearContexts

void clearContexts()

Warning:This interface is no longer functional from the SAP BusinessObjects XI 4.0 release onwards.

Clears any contexts set for any data provider, as DataProvider.clearContexts(). When used in combination with Query.resetContexts(), calling this method will ensure that any contexts will be prompted upon the next refresh.

Since:

12.0

See Also:

Contexts, DocumentInstance.getMustFillContexts(), DocumentInstance.getContextPrompts()