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

java.lang.Object
  extended by org.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 CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE
          The fetch size on column and row edge in cube cursor.
static java.lang.String CUBECURSOR_FETCH_LIMIT_ON_LEVEL
          Deprecated. use DataEngine.CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE and DataEngine.CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE instead
static java.lang.String CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE
           
static java.lang.String DATA_SET_CACHE_DELTA_FILE
           
static java.lang.String DATA_SET_CACHE_ROW_LIMIT
          Indicates whether data set cache function need to be used: Negative integer: Enable data set cache.
static java.lang.String DATASET_CACHE_OPTION
          Deprecated.  
static java.lang.String IN_MEMORY_CUBE_SIZE
          The size of cube to be saved in memory rather than in disk.
static java.lang.String INCREMENTAL_CACHE_CONFIG
          data set incremental cache file URL.
static java.lang.String MEMORY_BUFFER_SIZE
          Indicate the size of data cached for each result set.We only accept positive integer as input, the unit of which would be MB.
static java.lang.String MEMORY_DATA_SET_CACHE
          Indicates whether memory data set cache function need to be used: Positive integer: Enable memory data set cache.
 
Constructor Summary
DataEngine()
           
 
Method Summary
abstract  void addShutdownListener(IShutdownListener listener)
          Add a shut down listener.
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  IResultMetaData getCachedDataSetMetaData(IBaseDataSourceDesign dataSource, IBaseDataSetDesign dataSet)
          This method will return NULL if the named data set is not cached.
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.eclipse.birt.core.framework.PlatformConfig platformConfig, DataEngineContext dataContext)
           
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  org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ICubeQueryDefinition query, java.util.Map appContext)
          Prepare the cube query definition, return an IPreparedCubeQuery instance
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  org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ISubCubeQueryDefinition query, java.util.Map appContext)
          Prepare the sub cube query definition, return an IPreparedCubeQuery instance
abstract  void registerQueries(IDataQueryDefinition[] queryDefns)
          Optimize query execution by analyze a list of query definitions.
abstract  void removeListener(IShutdownListener listener)
          Remove a shut down listener.
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
Deprecated. 
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)

DATA_SET_CACHE_ROW_LIMIT

public static java.lang.String DATA_SET_CACHE_ROW_LIMIT
Indicates whether data set cache function need to be used: Negative integer: Enable data set cache. The row limit will not be set and all data set rows are fetched. Positive integer: Enable data set cache. This row limit will be used for ALL data sets, regardless of settings on individual data set designs. Zero:Disable data set cache regardless of report design settings and DataEngineContext settings.


MEMORY_BUFFER_SIZE

public static java.lang.String MEMORY_BUFFER_SIZE
Indicate the size of data cached for each result set.We only accept positive integer as input, the unit of which would be MB.


DATA_SET_CACHE_DELTA_FILE

public static java.lang.String DATA_SET_CACHE_DELTA_FILE

MEMORY_DATA_SET_CACHE

public static java.lang.String MEMORY_DATA_SET_CACHE
Indicates whether memory data set cache function need to be used: Positive integer: Enable memory data set cache. This row limit will be used for ALL data sets, regardless of settings on individual data set designs. Zero:Disable memory data set cache regardless of report design settings and DataEngineContext settings.


INCREMENTAL_CACHE_CONFIG

public static java.lang.String INCREMENTAL_CACHE_CONFIG
data set incremental cache file URL.


CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE

public static java.lang.String CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE
The fetch size on column and row edge in cube cursor. Positive integer: the number setting on edge. Zero or Negative number:Disable the number setting on edge.


CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE

public static java.lang.String CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE

CUBECURSOR_FETCH_LIMIT_ON_LEVEL

public static java.lang.String CUBECURSOR_FETCH_LIMIT_ON_LEVEL
Deprecated. use DataEngine.CUBECURSOR_FETCH_LIMIT_ON_COLUMN_EDGE and DataEngine.CUBECUSROR_FETCH_LIMIT_ON_ROW_EDGE instead
The fetch size of the member numbers for all levels. Positive integer: the member numbers will be fetched from levels. Zero or Negative integer:Disable this number setting on levels.


IN_MEMORY_CUBE_SIZE

public static java.lang.String IN_MEMORY_CUBE_SIZE
The size of cube to be saved in memory rather than in disk. The unit is MB. In case that the size of materialized cube exceed the assigned memory size, the disk will automatically be used.

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

Parameters:
context, - When this value is null, a default context will be used. The default context is DataEngineContext.MODE_DIRECTPRESENT.
Returns:
an instance of DataEngine under specified context

newDataEngine

public static DataEngine newDataEngine(org.eclipse.birt.core.framework.PlatformConfig platformConfig,
                                       DataEngineContext dataContext)
                                throws org.eclipse.birt.core.exception.BirtException
Parameters:
context -
Returns:
Throws:
org.eclipse.birt.core.exception.BirtException

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

getCachedDataSetMetaData

public abstract IResultMetaData getCachedDataSetMetaData(IBaseDataSourceDesign dataSource,
                                                         IBaseDataSetDesign dataSet)
                                                  throws org.eclipse.birt.core.exception.BirtException
This method will return NULL if the named data set is not cached. Otherwise, it will return an IResultMetaData instance which provides at least the ColumnName and ColumnType information for all cached columns. Please note that the ParameterHint information will usually essential to the result of data set design is omitted for it has nothing to do with the metadata.

Parameters:
dataSource -
dataSet -
parameterHints -
Returns:
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.

Parameters:
dataSource, - which is associated with the data set
dataSet, - which cache needs to be cleared
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

registerQueries

public abstract void registerQueries(IDataQueryDefinition[] queryDefns)
                              throws org.eclipse.birt.data.engine.core.DataException
Optimize query execution by analyze a list of query definitions.

Parameters:
queryDefns -
Throws:
org.eclipse.birt.data.engine.core.DataException

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

prepare

public abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ICubeQueryDefinition query,
                                                                                 java.util.Map appContext)
                                                                          throws org.eclipse.birt.core.exception.BirtException
Prepare the cube query definition, return an IPreparedCubeQuery instance

Parameters:
query -
appContext -
Returns:
Throws:
org.eclipse.birt.core.exception.BirtException

prepare

public abstract org.eclipse.birt.data.engine.olap.api.IPreparedCubeQuery prepare(org.eclipse.birt.data.engine.olap.api.query.ISubCubeQueryDefinition query,
                                                                                 java.util.Map appContext)
                                                                          throws org.eclipse.birt.core.exception.BirtException
Prepare the sub cube query definition, return an IPreparedCubeQuery instance

Parameters:
query -
appContext -
Returns:
Throws:
org.eclipse.birt.core.exception.BirtException

addShutdownListener

public abstract void addShutdownListener(IShutdownListener listener)
Add a shut down listener. When the data engine shut down the listener will be notified.


removeListener

public abstract void removeListener(IShutdownListener listener)
Remove a shut down listener.

Parameters:
listener -

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 © 2008 Actuate Corp. All rights reserved.