org.eclipse.birt.data.engine.api
Class DataEngine

java.lang.Object
  extended byorg.eclipse.birt.data.engine.api.DataEngine

public abstract class DataEngine
extends java.lang.Object

Data Engine API class.
Provides methods to define data sources and data sets, and to prepare a IQueryDefinition. An application typically needs only one instance of this class, which can be used to prepare and execute multiple data queries.

User of this class must always call the shutdown method when it is done with an instance of this class to ensure release of all data source connections and related resources.


Field Summary
static java.lang.String DATASET_CACHE_OPTION
          Indicates whether data set cache function needs to be used.
 
Constructor Summary
DataEngine()
           
 
Method Summary
abstract  void clearCache(IBaseDataSourceDesign dataSource, IBaseDataSetDesign dataSet)
          If user wants to use the latest data from data set rather than local cache, user needs to call this clearCache method to delete the cache content from update local environment.
abstract  void closeDataSource(java.lang.String dataSourceName)
          Provides a hint to DtE that the consumer is done with the given data source, and that its resources can be safely released as appropriate.
abstract  void defineDataSet(IBaseDataSetDesign dataSet)
          Provides the definition of a data set to Data Engine.
abstract  void defineDataSource(IBaseDataSourceDesign dataSource)
          Provides the definition of a data source to Data Engine.
abstract  IQueryResults getQueryResults(java.lang.String queryResultID)
          If and only if current mode is DataEngineContext.MODE_PRESENTATION, query result can be retrieved from report document.
static DataEngine newDataEngine(DataEngineContext context)
          Creates a new instance of DataEngine, using the specified DataEngineContext as its running environment
static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope)
          Deprecated. use newDataEngine( DataEngineContext context ) instead
static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope, java.io.File homeDir)
          Deprecated. Use newDataEngine(Scriptable) instead. Home Dir is no longer used.
abstract  IPreparedQuery prepare(IQueryDefinition querySpec)
          Verifies the elements of a report query spec and provides a hint to the query to prepare and optimize an execution plan.
abstract  IPreparedQuery prepare(IQueryDefinition querySpec, java.util.Map appContext)
          Verifies the elements of a report query spec, and provides a hint and application context object(s) to the query to prepare and optimize an execution plan.
abstract  void shutdown()
          Shuts down this instance of data engine, and releases all associated resources.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DATASET_CACHE_OPTION

public static java.lang.String DATASET_CACHE_OPTION
Indicates whether data set cache function needs to be used. If yes, put a true value of this property to appContext and set it by the method of prepare.

See Also:
org.eclipse.birt.data.engine.api.DataEngine.prepare( IQueryDefinition querySpec, Map appContext)
Constructor Detail

DataEngine

public DataEngine()
Method Detail

newDataEngine

public static DataEngine newDataEngine(DataEngineContext context)
Creates a new instance of DataEngine, using the specified DataEngineContext as its running environment

Returns:
an instance of DataEngine under specified context

newDataEngine

public static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope)
Deprecated. use newDataEngine( DataEngineContext context ) instead

Creates a new instance of DataEngine, using the specified Javascript scope and home directory setting.

Parameters:
sharedScope - a Javascript scope to be used as the "shared" scope to evaluate Javascript expressions by the data engine.

newDataEngine

public static DataEngine newDataEngine(org.mozilla.javascript.Scriptable sharedScope,
                                       java.io.File homeDir)
Deprecated. Use newDataEngine(Scriptable) instead. Home Dir is no longer used.


getQueryResults

public abstract IQueryResults getQueryResults(java.lang.String queryResultID)
                                       throws org.eclipse.birt.core.exception.BirtException
If and only if current mode is DataEngineContext.MODE_PRESENTATION, query result can be retrieved from report document. Otherwise a BirtException will be thrown immediatelly.

Parameters:
queryResultID -
Returns:
an instanceof IQueryResults
Throws:
org.eclipse.birt.core.exception.BirtException

defineDataSource

public abstract void defineDataSource(IBaseDataSourceDesign dataSource)
                               throws org.eclipse.birt.core.exception.BirtException
Provides the definition of a data source to Data Engine. A data source must be defined using this method prior to preparing any report query that uses such data source.
Data sources are uniquely identified name. If specified data source has already been defined, its definition will be updated with the content of the provided definition object.

Throws:
org.eclipse.birt.core.exception.BirtException

defineDataSet

public abstract void defineDataSet(IBaseDataSetDesign dataSet)
                            throws org.eclipse.birt.core.exception.BirtException
Provides the definition of a data set to Data Engine. A data set must be defined using this method prior to preparing any report query that uses such data set.
Data sets are uniquely identified name. If specified data set has already been defined, its definition will be updated with the content of the provided definition object.

Throws:
org.eclipse.birt.core.exception.BirtException

clearCache

public abstract void clearCache(IBaseDataSourceDesign dataSource,
                                IBaseDataSetDesign dataSet)
                         throws org.eclipse.birt.core.exception.BirtException
If user wants to use the latest data from data set rather than local cache, user needs to call this clearCache method to delete the cache content from update local environment. After it is called, in the next time the data will be retrieved again from data source to update cache.

Throws:
org.eclipse.birt.core.exception.BirtException

prepare

public abstract IPreparedQuery prepare(IQueryDefinition querySpec)
                                throws org.eclipse.birt.core.exception.BirtException
Verifies the elements of a report query spec and provides a hint to the query to prepare and optimize an execution plan. The given querySpec could be a IQueryDefinition (raw data transform) spec based on static definition found in a report design.

This report query spec could be further refined during engine execution after having resolved any related runtime condition. For example, a nested report item might not be rendered based on a runtime condition. Thus its associated data expression could be removed from the report query defn given to DtE to prepare.

During prepare, the DTE does not open a data set. In other words, any beforeOpen script on a data set will not be evaluated at this stage.

Parameters:
querySpec - Specifies the data access and data transforms services needed from DtE to produce a set of query results.
Returns:
The IPreparedQuery object that contains a prepared query ready for execution.
Throws:
org.eclipse.birt.data.engine.core.DataException - if error occurs during the preparation of querySpec
org.eclipse.birt.core.exception.BirtException

prepare

public abstract IPreparedQuery prepare(IQueryDefinition querySpec,
                                       java.util.Map appContext)
                                throws org.eclipse.birt.core.exception.BirtException
Verifies the elements of a report query spec, and provides a hint and application context object(s) to the query to prepare and optimize an execution plan.
This has the same behavior as the prepare( IQueryDefinition querySpec ) method, with an additional argument for an application to pass in a context map to the underlying data provider, e.g. an ODA run-time driver.

Parameters:
querySpec - Specifies the data access and data transforms services needed from DtE to produce a set of query results.
appContext - The application context map for preparation and execution of the querySpec; could be null.
Returns:
The IPreparedQuery object that contains a prepared query ready for execution.
Throws:
org.eclipse.birt.core.exception.BirtException - if error occurs during the preparation of querySpec
Since:
2.0

closeDataSource

public abstract void closeDataSource(java.lang.String dataSourceName)
                              throws org.eclipse.birt.core.exception.BirtException
Provides a hint to DtE that the consumer is done with the given data source, and that its resources can be safely released as appropriate. This tells DtE that there is to be no more query that uses such data source.

Parameters:
dataSourceName - The name of a data source. The named data source must have been previously defined.
Throws:
org.eclipse.birt.core.exception.BirtException

shutdown

public abstract void shutdown()
Shuts down this instance of data engine, and releases all associated resources. This method should be called when the caller is done with an instance of the data engine.



Copyright © 2005 Actuate Corp. All rights reserved.